init

3 files changed, 553 insertions, 0 deletions

diff --git a/Library/Homebrew/cask/doc/development/adding_a_cask.md b/Library/Homebrew/cask/doc/development/adding_a_cask.md
new file mode 100644
index 000000000..d69966a2a
--- /dev/null
+++ b/Library/Homebrew/cask/doc/development/adding_a_cask.md
@@ -0,0 +1,314 @@
+## Adding a Cask
+
+Making a new Cask is easy. Follow the directions in [Getting Set Up To Contribute](../../CONTRIBUTING.md#getting-set-up-to-contribute) to begin.
+
+### Examples
+
+Here’s a Cask for `shuttle` as an example. Note the comment above `url`, which is needed when [the url and homepage hostnames differ](../cask_language_reference/stanzas/url.md#when-url-and-homepage-hostnames-differ-add-a-comment)
+
+```ruby
+cask 'shuttle' do
+  version '1.2.6'
+  sha256 '7b54529cd00332e423839cf768b732ac6c42e17de9325d0a093764180deeb611'
+
+  # github.com/fitztrev/shuttle was verified as official when first introduced to the cask
+  url "https://github.com/fitztrev/shuttle/releases/download/v#{version}/Shuttle.zip"
+  appcast 'https://github.com/fitztrev/shuttle/releases.atom',
+          checkpoint: 'c3dea2ed479b3ebba7c56ace6040901795f6dc6be92f9ffc30cc808d31723f17'
+  name 'Shuttle'
+  homepage 'https://fitztrev.github.io/shuttle/'
+  license :mit
+
+  app 'Shuttle.app'
+
+  zap delete: '~/.shuttle.json'
+end
+```
+
+And here is one for `airstream`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check` (necessary since the checksum will change when a new distribution is made available). This combination of `version :latest` and `sha256 :no_check` is currently the preferred mechanism when a versioned download URL is not available.
+
+```ruby
+cask 'airstream' do
+  version :latest
+  sha256 :no_check
+
+  # amazonaws.com/airstream-clients was verified as official when first introduced to the cask
+  url 'https://s3-us-west-2.amazonaws.com/airstream-clients/mac/airstream-mac.dmg'
+  name 'AirStream'
+  homepage 'http://airstream.io/download/'
+  license :gratis
+
+  app 'AirStream.app'
+
+  caveats do
+    depends_on_java('6')
+  end
+end
+```
+
+Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](../cask_language_reference/stanzas/uninstall.md#uninstall-key-pkgutil), which is needed to uninstall all files which were installed using the installer.
+
+```ruby
+cask 'airdisplay' do
+  version '3.0.3'
+  sha256 'db84a66fe3522929a0afa58a4fe0189977baded89df0035ead1ccd334f7b8126'
+
+  url "https://www.avatron.com/updates/software/airdisplay/ad#{version.no_dots}.zip"
+  appcast 'https://avatron.com/updates/software/airdisplay/appcast.xml',
+          checkpoint: '938bdb9fbee793dce92818366cb2c19ba84c5b0cd6853fd893897d4a40689bc2'
+  name 'Air Display'
+  homepage 'https://avatron.com/apps/air-display/'
+  license :commercial
+
+  pkg 'Air Display Installer.pkg'
+
+  uninstall pkgutil: 'com.avatron.pkg.AirDisplay'
+end
+```
+
+### Generating a Token for the Cask
+
+The Cask **token** is the mnemonic string people will use to interact with the Cask via `brew cask install`, `brew cask search`, etc. The name of the Cask **file** is simply the token with the extension `.rb` appended.
+
+The easiest way to generate a token for a Cask is to run this command:
+
+```bash
+$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/generate_cask_token" '/full/path/to/new/software.app'
+```
+
+If the software you wish to Cask is not installed, or does not have an associated App bundle, just give the full proper name of the software instead of a pathname:
+
+```bash
+$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/generate_cask_token" 'Google Chrome'
+```
+
+If the `generate_cask_token` script does not work for you, see [Cask Token Details](#cask-token-details).
+
+### The `brew cask create` Command
+
+Once you know the token, create your Cask with the handy-dandy `brew cask create` command:
+
+```bash
+$ brew cask create my-new-cask
+```
+
+This will open `$EDITOR` with a template for your new Cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this:
+
+```ruby
+cask 'my-new-cask' do
+  version ''
+  sha256 ''
+
+  url ''
+  name ''
+  homepage ''
+  license :unknown # TODO: change license and remove this comment; ':unknown' is a machine-generated placeholder
+
+  app ''
+end
+```
+
+### Cask Stanzas
+
+Fill in the following stanzas for your Cask:
+
+| name               | value       |
+| ------------------ | ----------- |
+| `version`          | application version; give the value `:latest` if only an unversioned download is available
+| `sha256`           | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be suppressed by using the special value `:no_check`. (see [sha256](../cask_language_reference/stanzas/sha256.md))
+| `url`              | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />A [comment](../cask_language_reference/stanzas/url.md#when-url-and-homepage-hostnames-differ-add-a-comment) should be added if the hostnames in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit.<br />See [URL Stanza Details](../cask_language_reference/stanzas/url.md) for more information.
+| `name`             | the full and proper name defined by the vendor, and any useful alternate names (see [Name Stanza Details](../cask_language_reference/stanzas/name.md))
+| `homepage`         | application homepage; used for the `brew cask home` command
+| `license`          | a symbol identifying the license for the application. Valid category licenses include `:oss`, `:closed`, and `:unknown`. It is OK to leave as `:unknown`. (see [License Stanza Details](../cask_language_reference/stanzas/license.md))
+| `app`              | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [App Stanza Details](../cask_language_reference/stanzas/app.md))
+
+Other commonly-used stanzas are:
+
+| name               | value       |
+| ------------------ | ----------- |
+| `appcast`          | a URL providing an appcast feed to find updates for this Cask. (see [Appcast Stanza Details](../cask_language_reference/stanzas/appcast.md))
+| `pkg`              | relative path to a `.pkg` file containing the distribution (see [Pkg Stanza Details](../cask_language_reference/stanzas/pkg.md))
+| `caveats`          | a string or Ruby block providing the user with Cask-specific information at install time (see [Caveats Stanza Details](../cask_language_reference/stanzas/caveats.md))
+| `uninstall`        | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see [Uninstall Stanza Details](../cask_language_reference/stanzas/uninstall.md))
+
+Additional `artifact` stanzas you might need for special use-cases can be found [here](../cask_language_reference/all_stanzas.md#at-least-one-artifact-stanza-is-also-required). Even more special-use stanzas are listed at [Optional Stanzas](../cask_language_reference/all_stanzas.md#optional-stanzas).
+
+### Cask Token Details
+
+If a token conflicts with an already-existing Cask, authors should manually make the new token unique by prepending the vendor name. Example: [unison.rb](../../Casks/unison.rb) and [panic-unison.rb](../../Casks/panic-unison.rb).
+
+If possible, avoid creating tokens which differ only by the placement of hyphens.
+
+To generate a token manually, or to learn about exceptions for unusual cases, see [token_reference.md](../cask_language_reference/token_reference.md).
+
+### Archives With Subfolders
+
+When a downloaded archive expands to a subfolder, the subfolder name must be included in the `app` value.
+
+Example:
+
+1. Texmaker is downloaded to the file `TexmakerMacosxLion.zip`.
+2. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`.
+3. The folder `TexmakerMacosxLion` contains the application `texmaker.app`.
+4. So, the `app` stanza should include the subfolder as a relative path:
+
+  ```ruby
+  app 'TexmakerMacosxLion/texmaker.app'
+  ```
+
+
+## Testing Your New Cask
+
+Give it a shot with `brew cask install my-new-cask`.
+
+Did it install? If something went wrong, `brew cask uninstall my-new-cask` and edit your Cask with `brew cask edit my-new-cask` to fix it.
+
+If everything looks good, you’ll also want to make sure your Cask passes audit with:
+
+```bash
+brew cask audit my-new-cask --download
+```
+
+You should also check stylistic details with `brew cask style`:
+
+```bash
+$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
+$ brew cask style Casks/my-new-cask.rb [--fix]
+```
+
+Keep in mind all of these checks will be made when you submit your PR, so by doing them in advance you’re saving everyone a lot of time and trouble.
+
+If your application and Homebrew-Cask do not work well together, feel free to [file an issue](https://github.com/caskroom/homebrew-cask#reporting-bugs) after checking out open issues.
+
+## Finding a Home For Your Cask
+
+We maintain separate Taps for different types of binaries. Our nomenclature is:
+
++ **Stable**: The latest version provided by the developer defined by them as such.
++ **Beta, Development, Unstable**: Subsequent versions to **stable**, yet incomplete and under development, aiming to eventually become the new **stable**.
++ **Nightly**: Constantly up-to-date versions of the current development state.
++ **Legacy**: Any **stable** version that is not the most recent.
++ **Alternative**: Alternative edition of an existing app, by the same vendor (developer editions, community editions, pro editions, …).
++ **Regional, Localized**: Any version that isn’t the US English one, when that exists.
++ **Trial**: Date-limited version that stops working entirely after it expires, requiring payment to lift the limitation.
++ **Freemium**: Gratis version that works indefinitely but with limitations that can be removed by paying.
++ **Fork**: An alternate version of an existing project, with a based-on but modified source and binary.
++ **Unofficial**: An *allegedly* unmodified compiled binary, by a third-party, of a binary that has no existing build by the owner of the source code.
++ **Vendorless**: A binary distributed without an official website, like a forum posting.
++ **Walled**: When the download URL is both behind a login/registration form and from a host that differs from the homepage.
+
+### Stable Versions
+
+Stable versions live in the main repository at [caskroom/homebrew-cask](https://github.com/caskroom/homebrew-cask). They should run on the latest release of macOS or the previous point release (in 2015, for example, that meant El Capitan and Yosemite).
+
+### But There Is No Stable Version!
+
+When an App is only available as beta, development, or unstable versions, or in cases where such a version is the general standard, then said version can go into the main repo.
+
+### Beta, Unstable, Development, Nightly, Legacy, or Alternative Versions
+
+When an App has a principal stable version, alternative versions should be submitted to [caskroom/homebrew-versions](https://github.com/caskroom/homebrew-versions).
+
+### Regional and Localized
+
+When an App exists in more than one language or has different regional editions, the US English one belongs in the main repo, and all the others in [caskroom/homebrew-versions](https://github.com/caskroom/homebrew-versions). When not already part of the name of the App, a [regional identifier](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and a [language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) are to be appended to the Cask’s token (both when available, or just the appropriate one when not).
+
+### Trial and Freemium Versions
+
+Before submitting a trial, make sure it can be made into a full working version without the need to be redownloaded. If an App provides a trial but the only way to buy the full version is via the Mac App Store, it does not belong in any of the official repos. Freemium versions are fine.
+
+### Forks and Apps with Conflicting Names
+
+Forks should have the vendor’s name as a prefix on the Cask’s file name and token. For unrelated Apps that share a name, the most popular one (usually the one already present) stays unprefixed. Since this can be subjective, if you disagree with a decision open an issue and make your case to the maintainers.
+
+### Unofficial, Vendorless, and Walled Builds
+
+We do not accept these casks since they offer a higher-than-normal security risk. [alehouse/homebrew-unofficial](https://github.com/alehouse/homebrew-unofficial) is a sister repo where you may wish to submit your cask.
+
+### Fonts
+
+Font Casks live in the [caskroom/homebrew-fonts](https://github.com/caskroom/homebrew-fonts) repository. See the font repo [CONTRIBUTING.md](../../../../../homebrew-fonts/blob/master/CONTRIBUTING.md)
+for details.
+
+## Submitting Your Changes
+
+Hop into your Tap and check to make sure your new Cask is there:
+
+```bash
+$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
+$ git status
+# On branch master
+# Untracked files:
+#   (use "git add <file>..." to include in what will be committed)
+#
+#       Casks/my-new-cask.rb
+```
+
+So far, so good. Now make a feature branch that you’ll use in your pull request:
+
+```bash
+$ git checkout -b my-new-cask
+Switched to a new branch 'my-new-cask'
+```
+
+Stage your Cask with `git add Casks/my-new-cask.rb`. You can view the changes that are to be committed with `git diff --cached`.
+
+Commit your changes with `git commit -v`.
+
+### Commit Messages
+
+For any git project, some good rules for commit messages are:
+
+* The first line is commit summary, 50 characters or less,
+* Followed by an empty line,
+* Followed by an explanation of the commit, wrapped to 72 characters.
+
+See [a note about git commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more.
+
+The first line of a commit message becomes the **title** of a pull request on GitHub, like the subject line of an email. Including the key info in the first line will help us respond faster to your pull.
+
+For Cask commits in the Homebrew-Cask project, we like to include the Application name, version number (or `:latest`), and purpose of the commit in the first line.
+
+Examples of good, clear commit summaries:
+
+* `Add Transmission.app v1.0`
+* `Upgrade Transmission.app to v2.82`
+* `Fix checksum in Transmission.app Cask`
+* `Add CodeBox Latest`
+
+Examples of difficult, unclear commit summaries:
+
+* `Upgrade to v2.82`
+* `Checksum was bad`
+
+### Pushing
+
+Push your changes to your GitHub account:
+
+```bash
+$ github_user='<my-github-username>'
+$ git push "$github_user" my-new-cask
+```
+
+If you are using [GitHub two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) and set your remote repository as HTTPS you will need to set up a personal access token and use that instead of your password. Further information [here](https://help.github.com/articles/https-cloning-errors/#provide-access-token-if-2fa-enabled).
+
+### Squashing
+
+If your pull request has multiple commits which revise the same lines of code, or if you make some changes after comments from one of the maintainers, it is better to [squash](https://davidwalsh.name/squash-commits-git) those commits together into one logical unit.
+
+But you don’t always have to squash — it is fine for a pull request to contain multiple commits when there is a logical reason for the separation.
+
+### Filing a Pull Request on GitHub
+
+Now go to the [`homebrew-cask` GitHub repository](https://github.com/caskroom/homebrew-cask). GitHub will often show your `my-new-cask` branch with a handy button to `Compare & pull request`. Otherwise, click the `New pull request` button and choose to `compare across forks`. The base fork should be `caskroom/homebrew-cask @ master`, and the head fork should be `my-github-username/homebrew-cask @ my-new-cask`. You can also add any further comments to your pull request at this stage.
+
+Congratulations! You are done now, and your Cask should be pulled in or otherwise noticed in a while. If a maintainer suggests some changes, just make them on the `my-new-cask` branch locally, [squash](#squashing), and [push](#pushing).
+
+## Cleaning up
+
+After your Pull Request is submitted, you should get yourself back onto `master`, so that `brew update` will pull down new Casks properly:
+
+```bash
+cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
+git checkout master
+```
diff --git a/Library/Homebrew/cask/doc/development/hacking.md b/Library/Homebrew/cask/doc/development/hacking.md
new file mode 100644
index 000000000..707ea1f71
--- /dev/null
+++ b/Library/Homebrew/cask/doc/development/hacking.md
@@ -0,0 +1,160 @@
+# Hacking on Homebrew-Cask
+
+If you’d like to hack on the Ruby code that drives this project, please join us, we’d love to have you!
+
+## Goals, Design, and Philosophy
+
+Homebrew-Cask is an attempt to make a Linux-style package manager for precompiled macOS software. Homebrew-Cask is not yet as featureful as `apt` or `yum`, but we are trying to be as close as we can get to those tools from the user’s point of view.
+
+We manage installed files via the “symlink farm” method, like [GNU Stow](https://www.gnu.org/software/stow/) and [Homebrew](http://brew.sh/). Similarly, we try to avoid `sudo` where possible.
+
+Homebrew-Cask is designed to work like a traditional Unix tool:
+
+* All functionality should be accessible from the CLI. The user should be freed (**freed!**) from interacting with a GUI.
+* Homebrew-Cask should itself be scriptable.
+
+## Project Status
+
+Homebrew-Cask is still young, and should be considered in alpha.
+
+We have good support for a variety of artifacts: apps, pkgs, binaries, plugins, and [fonts](https://github.com/caskroom/homebrew-fonts/). Homebrew-Cask can install and uninstall any of those. However, these commands don’t work well with multiple versions, and most importantly, we currently can’t `upgrade`.
+
+Since upgrading is a core feature of every package manager, the implementation of an `upgrade` verb is our top priority. For `upgrade` to work reliably, we must:
+
+* Maintain unequivocal version information from a variety of sources,
+* Track version-specific uninstallation,
+* Play nice with self-updating software.
+
+These and more requirements are tracked in our [`upgrade` roadmap](https://github.com/caskroom/homebrew-cask/issues/4678). If you’d like to contribute to `upgrade`, that’s an excellent place to start.
+
+## Homebrew and Homebrew-Cask
+
+Homebrew-Cask is independent of Homebrew as a project.
+
+The Homebrew-Cask CLI is implemented as a Homebrew subcommand, so we try to match semantics wherever possible. That means that similar functionality should have similar flags and parameters.
+
+However, very little backend code is shared between the two projects. The Homebrew codebase is based on how Homebrew Formulae work, and our Casks are very different from Formulae.
+
+### Casks and Formulae
+
+Homebrew Formulae deal with many different build processes, and often include arbitrary Ruby code.
+
+Casks, by contrast, only need to support the few installation methods used by apps, pkg installers, and so on, making them suitable for a [declarative DSL](../cask_language_reference/).
+
+We encourage Cask authors to use the DSL as much as possible, since that makes things easier for everyone: from maintainers who review pull requests, to first-time contributors, to people who are unfamiliar with Ruby but would like to help.
+
+For software with unusual needs that are not covered by the DSL, we generally accept Casks containing small hacks or arbitrary code. If the hack becomes common enough, we extend the DSL with a simple shorthand that offers the same (or better) functionality.
+
+## Contributing
+
+### Setup
+
+Cask authors often work directly within the Homebrew directory under `/usr/local`. For coding, that is usually not sufficient.
+
+We recommend the following:
+
+1. Fork our repo: <https://github.com/caskroom/homebrew-cask/fork>
+
+2. Clone a private copy of the repo:
+
+  ```bash
+  git clone https://github.com/<username>/homebrew-cask.git
+  ```
+
+3. Add the official repo as the `upstream` remote:
+
+  ```bash
+  cd homebrew-cask
+  git remote add upstream https://github.com/caskroom/homebrew-cask.git
+  ```
+
+4. Now you have two copies of the Homebrew-Cask codebase on disk: the released version in `/usr/local/Library/Taps/caskroom/homebrew-cask`, and a development version in your private repo. To symlink the `Casks` and `rubylib` folders from `/usr/local/...` into your private repo, run the following script:
+
+  ```bash
+  /<path>/<to>/<private>/<repo>/developer/bin/develop_brew_cask
+  ```
+
+  Now you can hack on your private repo, and use the `brew cask` CLI like normal — it will interact with your latest code.
+
+5. Important: while in development mode, you can’t safely run Homebrew’s `brew update` command. To switch back to production mode, run:
+
+  ```bash
+  /<path>/<to>/<private>/<repo>/developer/bin/production_brew_cask
+  ```
+
+### Forcing a Ruby interpreter
+
+You can force a specific version of the Ruby interpreter, and/or an alternate version of the `brew-cask` subcommand, by invoking `brew cask` with fully-qualified paths, like this:
+
+```bash
+$ /System/Library/Frameworks/Ruby.framework/Versions/Current/usr/bin/ruby /usr/local/Library/Taps/caskroom/homebrew-cask/cmd/brew-cask.rb help
+```
+
+### Forcing a Specific Homebrew-Cask Subcommand
+
+If you are developing a subcommand, you can force `brew cask` to dispatch a specific file by giving a fully-qualified path to the file containing the subcommand, like this:
+
+```bash
+$ brew cask /usr/local/Library/Taps/caskroom/homebrew-cask/lib/hbc/cli/info.rb google-chrome
+```
+
+This form can also be combined with a specific Ruby interpreter as above.
+
+### Forcing a Specific macOS Release
+
+The environment variable `$MACOS_RELEASE` can be overridden at the command line for test purposes:
+
+```bash
+$ MACOS_RELEASE=10.9 brew cask info <cask>
+```
+
+The environment variable `$MACOS_RELEASE_WITH_PATCHLEVEL` is also available, though not consulted directly. Use `$MACOS_RELEASE` for testing.
+
+### Target Ruby Versions
+
+Homebrew-Cask requires a Ruby interpreter version 2.0 or above. This is the default system Ruby on Mavericks (10.9) and later.
+
+### Submitting Your Changes
+
+See [the relevant section in `adding_a_cask.md`](adding_a_cask.md#submitting-your-changes).
+
+#### Commit Messages
+
+The first line of a commit message (the summary line) is like the subject line of an email. (See [`adding_a_cask.md`](adding_a_cask.md#commit-messages)). A short but complete summary line helps the maintainers respond to your pull request more quickly.
+
+#### Mind the test suite!
+
+If you’re making changes - please write some tests for them! Install dependencies and run the whole test suite with:
+
+```bash
+brew cask-tests
+```
+
+Be sure to run the test suite before submitting. If you forget, Travis-CI will do that for you and embarrass you in front of all your friends. :)
+
+You may also use a set of environment variables to increase verbosity:
+
+* `TESTOPTS`, `TEST` etc. for the old [minitest suites](https://www.ruby-doc.org/stdlib-2.0.0/libdoc/rake/rdoc/Rake/TestTask.html)
+* `SPEC_OPTS`, `SPEC` etc. for [rspec suites](http://apidock.com/rspec/Spec/Rake/SpecTask)
+* `VERBOSE_TESTS` to see the standard output from the actual code = ignore the `shutup` helper
+
+Example of a very verbose output:
+
+```shell
+TESTOPTS='-v' SPEC_OPTS='-fd' VERBOSE_TESTS=1 brew cask-tests
+```
+
+#### External Commands
+
+Advanced users may create their own external commands for Homebrew-Cask by following conventions similar to external commands for git or Homebrew. An external command may be any executable on your `$PATH` which follows the form `brewcask-<command>`. (So long as `<command>` does not conflict with an existing command verb.) The command will be invoked by `exec` and passed any unprocessed arguments from the original command-line. An external command may also be implemented as an executable Ruby file, on your `$PATH`, which follows the form `brewcask-<command>.rb`. The Ruby file will be `required` and will have full access to the Ruby environments of both Homebrew-Cask and Homebrew. Example external commands may be found in `developer/examples`.
+
+## Hanging out on IRC
+
+We’re on IRC at `#homebrew-cask` on Freenode. If you are going to develop for Homebrew-Cask, it’s a great idea to hang out with us there. Here’s why:
+
+* Discuss your thoughts before coding and maybe get new ideas
+* Get feedback from the Travis-CI bot on build failures
+* Talk to [caskbot](https://github.com/passcod/caskbot) about checksums, version info, and releases
+* Just to be social!
+
+# <3 THANK YOU! <3
diff --git a/Library/Homebrew/cask/doc/development/maintaining.md b/Library/Homebrew/cask/doc/development/maintaining.md
new file mode 100644
index 000000000..26b9abbb0
--- /dev/null
+++ b/Library/Homebrew/cask/doc/development/maintaining.md
@@ -0,0 +1,79 @@
+# Maintaining Homebrew-Cask
+
+__vv NOTE - DRAFT DOC! vv__
+
+This doc is just at a starting point. The maintainers team will be collaborating on it and we’ll remove this header when we feel like it’s stable.
+
+__^^ NOTE - DRAFT DOC! ^^__
+
+As a relatively large open source project with plenty of daily activity, Homebrew-Cask requires regular care and feeding. This includes reviewing and merging PRs, diagnosing bugs, improving documentation, discussing project policy and features, and plenty more!
+
+This responsibility is shared by @caskroom/maintainers - a team of humans spanning the globe each of whom has agreed to dedicate some of their spare time to helping our dear users. What a kind and friendly bunch they must be! (It’s true, they are.)
+
+As the project matures and grows, so does the team of maintainers. It’s becoming more and more important to write down things that once were done ad-hoc.
+
+So here is where we are gathering details about how we maintain the project.
+
+## Things we focus on
+
+* We favor the user above all.
+* Any user that submits a PR to our little old project is solid gold - we do everything we can to make sure they have a good experience and that their work is appreciated.
+* Friendliness. In our minds, we are in a *friendliness contest* against other open-source projects. We want to be the nicest, most fun, most easygoing project in the universe.
+* Supporting each other. Help the other maintainers, and spread out the workload.
+
+## Reviewing Incoming Casks
+
+Casks are the lifeblood of this project, and they generate the most maintenance-requiring activity on the project.
+
+While we started as a tool for convenience, we’re working on adding safety and security to the list of things we do for our users. That means things like verifying download URLs, working to figure out file checksums when possible, *etc*.
+
+__TODO__: Maybe one of our more active Cask reviewers can fill in the things they look for in incoming Casks.
+
+## Labels
+
+Every open issue and pull request must have a label added to it, unless the maintainer immediately acts on it (closing/merging) after looking at it. Labels should be consistent across repositories: not every repository needs every label, but their meaning and color must be the same throughout. Currently, our labels are:
+
+Label | Description | Issues | Pull Requests
+----- | ----------- | :----: | :-----------:
+**bug** | Something isn’t working as expected. A modification/addition/removal. Must always be accompanied by **cask** or **core** | &#x2713; | &#x2713;
+**cask** | Relates directly to a cask. Must always be accompanied by **bug** or **enhancement**. | &#x2713; | &#x2713;
+**cask request** | Either a request for a new cask or a call for correction in an existing one. | &#x2713; |
+**outdated appcast** | An automated label, handled by the various scripts geared towards updating casks with outdated appcasts. Should never be applied manually. | &#x2713; | &#x2713;
+**chief bug** | When multiple people open new issues for the same bug, the main issue where its progression is being tracked should have this label. Every other one should be marked **duplicate** and closed. | &#x2713; |
+**core** | Relates directly to the code of the core, Homebrew-Cask itself. Must always be accompanied by **bug** or **enhancement**. | &#x2713; | &#x2713;
+**discussion** | A matter that benefits from discussion before a decision is to be made. Any opinion should be given by users and maintainers alike, even if that opinion is “I have no strong feelings on the matter”. | &#x2713; |
+**documentation** | Relates to the documentation. | &#x2713; | &#x2713;
+**duplicate** | An issue or pull request that is essentially the same as another. Should be immediately closed. | &#x2713; | &#x2713;
+**enhancement** | Something we want implemented. Must always be accompanied by **cask** or **core**. | &#x2713; | &#x2713;
+**future** | Something that can currently only be referenced and will only be possible to act upon in the future, after certain conditions are met. Currently references [changes to the installation behaviour](https://github.com/caskroom/homebrew-cask/issues/13201). To be used sparingly. | &#x2713; | &#x2713;
+**meta** | Relates to Homebrew-Cask itself as a project and its policies/decisions. | &#x2713; |
+**on hold** | A pull request that depends on another being merged before it itself can be as well. |  | &#x2713;
+**roadmap** | Roadmap for feature implementation. | &#x2713; |
+**ready to implement** | Usually accompanied by the closing of a **discussion** issue. It succinctly describes in points the implementation of something yet to be written, be it a feature or a documentation section. Anyone looking at such an issue can safely ignore every post following the top one, as it should always be kept up-to-date with the discussion. | &#x2713; |
+**travis** | Bug related to [Travis CI](https://travis-ci.org/). Must always be accompanied by **bug** or **enhancement**. | &#x2713; | &#x2713;
+**upstream** | Something we have no hand in, and can only be fixed with intervention from developers outside Homebrew-Cask. Always refers to a cask, and never to the core. | &#x2713; | &#x2713;
+**awaiting maintainer feedback** | A maintainer requires input from other maintainers to proceed. Other maintainers should occasionaly check this label and give their feedback on the subject, if able. | &#x2713; | &#x2713;
+**awaiting user reply** | A maintainer requires further action or information from the original poster to proceed. Particularly useful to weed out those cases where issues and pull requests would otherwise be left open indefinitely because the original poster never replies. | &#x2713; | &#x2713;
+
+## Reviewing Core PRs
+
+Occasionally we’ll get submissions from users that fix bugs or add features to Homebrew-Cask itself. There is a subset of our maintainers who are less familiar with Ruby and prefer to leave these review to folks with more experience with the language. This is AOK!
+
+## Handling Cask Update PRs
+
+The most common pull requests we get are to add or update Casks. [Vítor Galvão](https://github.com/vitorgalvao) has created [some excellent scripts](https://github.com/vitorgalvao/tiny-scripts) to make these rote changes more painless. You can use [`fastmerge`](https://github.com/vitorgalvao/tiny-scripts/blob/master/fastmerge) if the PR is ready to merge (everything looks fine, all tests passed). Sometimes, new contributors aren't aware of how to squash commits, posting something like “Please [squash your commits](https://davidwalsh.name/squash-commits-git). Thanks!” should help them out.
+
+If the PR has an error, you can use [`prfixmaster`](https://github.com/vitorgalvao/tiny-scripts/blob/master/prfixmaster) to make any necessary changes.
+
+Lastly, if you see an outdated cask that just needs a version bump, you can use [`cask-repair`](https://github.com/vitorgalvao/tiny-scripts/blob/master/cask-repair) to make the PR yourself quickly.
+
+## Tips
+
+* To keep your repository up to date with caskroom/master, you can create a custom bash function to save some typing. Feel free to adapt the following set of commands to your specific needs --> `cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask; git checkout master; git pull origin; git push "$GITHUB_USERNAME" master; git remote prune origin; git fetch -p origin; git remote update --prune`
+
+## Ideas for other things to include here
+
+* Productivity enhancing tips / tools / scripts that help with PR review, cask testing, etc.
+* General policies.
+* Documenting important decisions that have been made.
+* Maybe some philosophical points about the project.