2014-01-19 00:20:29 +08:00
# How To Contribute
2013-04-29 01:10:59 +08:00
2013-05-12 09:11:51 +08:00
So you want to contribute to the project. **THIS IS GREAT NEWS!** Seriously. We're
2014-02-23 03:45:53 +08:00
all pretty happy about this. Here's how to get started:
* [Getting Set Up To Contribute ](#getting-set-up-to-contribute )
* [Adding a Cask ](#adding-a-cask )
* [Testing Your New Cask ](#testing-your-new-cask )
* [Finding a Home For Your Cask ](#finding-a-home-for-your-cask )
* [Submitting Your Changes ](#submitting-your-changes )
* [Cleaning up ](#cleaning-up )
2013-04-29 01:10:59 +08:00
2014-01-19 00:20:29 +08:00
## Getting Set Up To Contribute
2013-04-29 01:10:59 +08:00
1. Fork the repository in GitHub with the 'Fork' button
2013-05-12 09:11:51 +08:00
2. Add your GitHub fork as a remote for your homebrew-cask Tap
```bash
2014-02-23 03:45:53 +08:00
$ github_user='< my-github-username > '
2014-05-09 08:02:48 +08:00
$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
2014-02-23 03:45:53 +08:00
$ git remote add "$github_user" "https://github.com/$github_user/homebrew-cask"
2013-05-12 09:11:51 +08:00
```
2013-04-29 01:10:59 +08:00
2014-02-23 03:45:53 +08:00
2013-04-29 01:10:59 +08:00
## Adding a Cask
2013-10-20 07:04:24 +08:00
Making a Cask is easy: a Cask is a small Ruby file.
2013-07-29 07:08:58 +08:00
2014-02-28 22:14:58 +08:00
### Examples
2014-01-31 14:26:38 +08:00
Here's a Cask for `Alfred.app` as an example. Note that you may repeat
2014-01-26 02:18:53 +08:00
the `link` stanza as many times as you need, to create multiple links:
2013-04-29 01:10:59 +08:00
2013-05-06 02:01:23 +08:00
```ruby
class Alfred < Cask
2014-06-07 08:55:33 +08:00
version '2.3_264'
sha256 'a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92'
2014-06-17 00:42:13 +08:00
url 'https://cachefly.alfredapp.com/Alfred_2.3_264.zip'
homepage 'http://www.alfredapp.com/'
2014-01-24 21:36:11 +08:00
link 'Alfred 2.app'
link 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
2013-07-29 07:08:58 +08:00
end
```
2014-01-31 14:26:38 +08:00
Here is another Cask for `Vagrant.pkg` :
2013-07-29 07:08:58 +08:00
```ruby
class Vagrant < Cask
2014-01-31 14:26:38 +08:00
version '1.4.3'
sha256 'e7ff13b01d3766829f3a0c325c1973d15b589fe1a892cf7f857da283a2cbaed1'
2014-06-17 00:42:13 +08:00
url 'https://dl.bintray.com/mitchellh/vagrant/Vagrant-1.4.3.dmg'
homepage 'http://www.vagrantup.com'
2014-09-10 22:54:06 +08:00
pkg 'Vagrant.pkg'
2014-01-31 14:26:38 +08:00
uninstall :script => { :executable => 'uninstall.tool', :input => %w[Yes] }
2013-05-06 02:01:23 +08:00
end
```
2013-04-29 01:10:59 +08:00
2014-01-18 00:23:31 +08:00
### Naming the Cask
We try to maintain consistent naming for the benefit of our users.
The Cask **name** is the string people will use to interact with the Cask
via `brew cask install` , `brew cask search` , etc. The Cask **file**
is simply the Cask name with the extension `.rb` appended.
The easiest way to name a Cask is to run this command:
```bash
2014-05-09 08:02:48 +08:00
$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/cask_namer" '/full/path/to/new/software.app'
2014-01-18 00:23:31 +08:00
```
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
2014-05-09 08:02:48 +08:00
$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/cask_namer" 'Google Chrome'
2014-01-18 00:23:31 +08:00
```
If the `cask_namer` script does not work for you, see [Cask Naming Details ](#cask-naming-details ).
2014-02-28 22:14:58 +08:00
### The `brew cask create` Command
2014-01-18 00:23:31 +08:00
Once you know the name for your Cask, create it with the handy-dandy
`brew cask create` command.
2013-04-29 01:10:59 +08:00
2013-05-12 09:11:51 +08:00
```bash
2014-02-23 03:45:53 +08:00
$ brew cask create my-new-cask
2013-05-12 09:11:51 +08:00
```
2013-04-29 01:10:59 +08:00
2014-01-18 00:23:31 +08:00
This will open `$EDITOR` with a template for your new Cask. Hyphens in the
Cask name indicate case-changes in the class name, so the Cask name
'my-new-cask' becomes class `MyNewCask` stored in file `my-new-cask.rb` .
Running the `create` command above will get you a template that looks like
this:
2013-04-29 01:10:59 +08:00
2013-05-12 09:11:51 +08:00
```ruby
class MyNewCask < Cask
version ''
2014-01-31 14:26:38 +08:00
sha256 ''
2014-06-17 00:42:13 +08:00
url ''
homepage ''
2013-05-29 22:31:04 +08:00
link ''
2013-05-12 09:11:51 +08:00
end
```
2013-05-12 05:15:49 +08:00
2014-02-28 22:14:58 +08:00
### Cask Stanzas
2014-02-23 03:45:53 +08:00
Fill in the following stanzas for your Cask:
2013-04-29 01:10:59 +08:00
2014-02-25 00:31:53 +08:00
| name | value |
2013-10-20 07:04:24 +08:00
| ------------------ | ----------- |
2013-12-08 02:16:58 +08:00
| __cask metadata__ | information about the Cask (required)
2014-02-25 00:31:53 +08:00
| `url` | URL to the `.dmg` /`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details ](doc/CASK_LANGUAGE_REFERENCE.md#url-stanza-details ))
2013-10-20 07:04:24 +08:00
| `homepage` | application homepage; used for the `brew cask home` command
2014-02-23 03:45:53 +08:00
| `version` | application version; give value of `'latest'` if versioned downloads are not offered
2014-05-08 20:35:07 +08:00
| `sha256` | SHA-256 checksum of the file downloaded from `url` , calculated by the command `shasum -a 256 <file>` . Can be suppressed for unversioned downloads by using the special value `:no_check` . (see also [Checksum Stanza Details ](doc/CASK_LANGUAGE_REFERENCE.md#checksum-stanza-details ))
2013-12-08 02:16:58 +08:00
| __artifact info__ | information about artifacts inside the Cask (can be specified multiple times)
2014-02-25 00:31:53 +08:00
| `link` | relative path to a file that should be linked into the `Applications` folder on installation (see also [Link Stanza Details ](doc/CASK_LANGUAGE_REFERENCE.md#link-stanza-details ))
2014-09-10 22:54:06 +08:00
| `pkg` | relative path to a `.pkg` file containing the distribution (see also [Pkg Stanza Details ](doc/CASK_LANGUAGE_REFERENCE.md#pkg-stanza-details ))
2014-09-10 23:25:55 +08:00
| `uninstall` | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details ](doc/CASK_LANGUAGE_REFERENCE.md#uninstall-stanza-details ))
2013-12-10 08:56:25 +08:00
2014-02-23 03:45:53 +08:00
Additional stanzas you might need for special use-cases:
2013-12-10 08:56:25 +08:00
2014-02-25 00:31:53 +08:00
| name | value |
2013-12-12 19:41:39 +08:00
| ------------------ | ----------- |
2013-11-11 06:07:03 +08:00
| `prefpane` | relative path to a preference pane that should be linked into the `~/Library/PreferencePanes` folder on installation
2013-12-08 13:32:41 +08:00
| `colorpicker` | relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation
2013-12-08 02:16:58 +08:00
| `qlplugin` | relative path to a QuickLook plugin that should be linked into the `~/Library/QuickLook` folder on installation
2013-11-26 21:38:43 +08:00
| `font` | relative path to a font that should be linked into the `~/Library/Fonts` folder on installation
2014-01-23 06:56:37 +08:00
| `widget` | relative path to a widget that should be linked into the `~/Library/Widgets` folder on installation (ALPHA: DOES NOT WORK YET)
2013-12-14 08:13:19 +08:00
| `service` | relative path to a service that should be linked into the `~/Library/Services` folder on installation
2014-02-23 03:45:53 +08:00
| `binary` | relative path to a binary that should be linked into the `/usr/local/bin` folder on installation
2014-01-14 01:21:44 +08:00
| `input_method` | relative path to a input method that should be linked into the `~/Library/Input Methods` folder on installation
2014-02-04 00:20:57 +08:00
| `screen_saver` | relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation
2013-12-10 08:56:25 +08:00
| `nested_container` | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc.
2014-02-25 00:31:53 +08:00
| `caveats` | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Details ](doc/CASK_LANGUAGE_REFERENCE.md#caveats-details ))
2014-02-28 22:14:58 +08:00
Even more special-use stanzas are listed at [Optional Stanzas ](doc/CASK_LANGUAGE_REFERENCE.md#optional-stanzas ) and [Legacy Stanzas ](doc/CASK_LANGUAGE_REFERENCE.md#legacy-stanzas ).
2013-12-10 08:56:25 +08:00
2013-10-20 07:04:24 +08:00
2014-02-23 03:45:53 +08:00
### SourceForge URLs
2014-02-15 10:26:53 +08:00
2014-02-23 03:45:53 +08:00
SourceForge projects are a common way to distribute binaries, but they
provide many different styles of URLs to get to the goods.
2013-11-06 12:07:11 +08:00
We prefer URLs of this format:
```
http://sourceforge.net/projects/$PROJECTNAME/files/latest/download
```
This lets the project maintainers choose the best URL for download.
2014-02-23 03:45:53 +08:00
If the "latest" URL does not point to a valid file for a Mac app, then we
fall back to this format:
2013-11-06 12:07:11 +08:00
```
http://downloads.sourceforge.net/sourceforge/$PROJECTNAME/$FILENAME.$EXT
```
2014-06-07 18:23:33 +08:00
### Dropbox URLs
Some projects **officially** (meaning the URL is linked from the official website)
distribute binaries via Dropbox.
Occasionally, instead of a direct download link, they send you to a preview page.
In these cases, you need to manually change the URL.
For example this preview link:
```
https://www.dropbox.com/s/xttkmuvu7hh72vu/MyFile.pdf
```
becomes
```
https://dl.dropboxusercontent.com/s/xttkmuvu7hh72vu/MyFile.pdf
```
More: https://www.dropbox.com/help/201/en
2014-02-26 19:42:56 +08:00
### Vendor URLs
When possible, it is best to use a download URL from the original developer
or vendor, rather than an aggregator such as macupdate.com.
2014-01-18 00:23:31 +08:00
### Cask Naming Details
2013-11-04 05:46:03 +08:00
2014-01-18 00:23:31 +08:00
If a Cask name conflicts with an already-existing Cask, authors should manually
make the new Cask name unique by prepending the vendor name. Example:
[unison.rb ](../Casks/unison.rb ) and [panic-unison.rb ](../Casks/panic-unison.rb ).
2013-11-04 05:46:03 +08:00
2014-01-18 00:23:31 +08:00
If possible, avoid creating Cask names which differ only by the placement of
hyphens.
2013-11-04 05:46:03 +08:00
2014-01-18 00:23:31 +08:00
To name a Cask manually, or to learn about exceptions for unusual cases, see [CASK_NAMING_REFERENCE.md ](doc/CASK_NAMING_REFERENCE.md ).
2013-11-04 05:46:03 +08:00
2014-02-03 22:49:45 +08:00
2014-02-23 03:45:53 +08:00
### Archives With Subfolders
2014-02-03 22:49:45 +08:00
2014-02-23 03:45:53 +08:00
When a downloaded archive expands to a subfolder, the subfolder name must be
included in the `link` value.
2014-02-03 22:49:45 +08:00
Example:
2014-02-23 03:45:53 +08:00
* Texmaker is downloaded to the file `TexmakerMacosxLion.zip` .
* `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion` .
* The folder `TexmakerMacosxLion` contains the application `texmaker.app` .
* So, the `link` stanza should include the subfolder as a relative path:
2014-02-06 22:44:51 +08:00
2014-02-23 03:45:53 +08:00
```ruby
link 'TexmakerMacosxLion/texmaker.app'
```
2014-02-06 22:44:51 +08:00
2014-02-23 03:45:53 +08:00
### Indenting
2014-02-06 22:44:51 +08:00
2014-02-23 03:45:53 +08:00
All Casks and code in the homebrew-cask project should be indented using two
spaces (never tabs).
2014-01-15 06:41:11 +08:00
2013-05-12 05:15:49 +08:00
2014-01-19 00:20:29 +08:00
## Testing Your New Cask
2013-04-29 01:10:59 +08:00
2013-05-12 09:11:51 +08:00
Give it a shot with `brew cask install my-new-cask`
2013-04-29 01:10:59 +08:00
2013-05-12 09:11:51 +08:00
Did it install? If something went wrong, `brew cask uninstall my-new-cask` and
edit your Cask to fix it.
2013-12-08 02:16:58 +08:00
If everything looks good, you'll also want to make sure your Cask passes audit
2013-07-06 18:35:14 +08:00
with
`brew cask audit my-new-cask --download`
2013-04-29 01:10:59 +08:00
If your application and homebrew-cask do not work well together, feel free to
2014-05-03 23:16:12 +08:00
[file an issue ](https://github.com/caskroom/homebrew-cask/issues ) after checking
2013-04-29 01:10:59 +08:00
out open issues.
2014-01-23 02:08:34 +08:00
2014-02-20 05:53:05 +08:00
## Finding a Home For Your Cask
2014-02-23 03:45:53 +08:00
We maintain separate Taps for different types of binaries.
### Latest Stable Versions
2014-05-03 23:16:12 +08:00
Latest stable versions live in the main repository at [caskroom/homebrew-cask ](https://github.com/caskroom/homebrew-cask ).
2014-02-23 03:45:53 +08:00
Software in the main repo should run on the latest release of OS X or the previous
point release (currently: Mavericks and Mountain Lion).
### But There Is No Stable Version!
2014-07-04 04:27:50 +08:00
When an App is only available as an unstable version (e.g. beta, nightly), or in cases where such a version is
2014-02-23 03:45:53 +08:00
the general standard, then an "unstable" version can go into the main repo.
2014-02-20 05:53:05 +08:00
2014-02-23 03:45:53 +08:00
### Unstable, Development, or Legacy Versions
When an App already exists in the main repo, alternate versions can be Casked
and submitted to [caskroom/homebrew-versions ](https://github.com/caskroom/homebrew-versions ).
2014-06-09 07:30:45 +08:00
### Trial Versions
Before submitting a trial, please 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 currently belong in any of the official repos.
2014-02-23 03:45:53 +08:00
### Unofficial Builds
When an App developer does not offer a binary download, please submit the
Cask to [caskroom/homebrew-unofficial ](http://github.com/caskroom/homebrew-unofficial ).
For a location to host unofficial builds, contact our sister project [alehouse ](https://github.com/alehouse ).
### Fonts
Font Casks live in the [caskroom/homebrew-fonts ](https://github.com/caskroom/homebrew-fonts )
repository. See the font repo [CONTRIBUTING.md ](https://github.com/caskroom/homebrew-fonts/blob/master/CONTRIBUTING.md )
for details.
2014-02-20 05:53:05 +08:00
2014-01-19 00:20:29 +08:00
## Submitting Your Changes
2013-05-12 09:11:51 +08:00
2013-12-08 02:16:58 +08:00
Hop into your Tap and check to make sure your new Cask is there:
2013-05-12 09:11:51 +08:00
```bash
2014-05-09 08:02:48 +08:00
$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
2014-02-23 03:45:53 +08:00
$ git status
2013-05-12 09:11:51 +08:00
# 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
2014-02-23 03:45:53 +08:00
$ git checkout -b my-new-cask
2013-05-12 09:11:51 +08:00
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` .
2014-01-19 00:49:34 +08:00
Commit your changes with `git commit -v` .
2013-05-12 09:11:51 +08:00
2014-01-19 00:49:34 +08:00
### Commit Messages
For any git project, some good rules for commit messages are
* the first line is commit summary, 50 characters or less,
2013-05-12 09:11:51 +08:00
* followed by an empty line
2014-01-19 00:49:34 +08:00
* 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, 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`
Examples of difficult, unclear commit summaries:
* `Upgrade to v2.82`
* `Checksum was bad`
2013-05-12 09:11:51 +08:00
2014-01-19 00:49:34 +08:00
### Pushing
2013-05-12 09:11:51 +08:00
Push your changes to your GitHub account:
```bash
2014-02-23 03:45:53 +08:00
$ github_user='< my-github-username > '
$ git push "$github_user" my-new-cask
2013-05-12 09:11:51 +08:00
```
2014-07-29 20:02:08 +08:00
If you are using [GitHub two-factor authentication ](https://github.com/blog/1614-two-factor-authentication )
2014-07-14 06:26:34 +08:00
and set your remote repository as HTTPS you will need to set up
a personal access token and use that instead your password.
See more on https://help.github.com/articles/https-cloning-errors#provide-access-token-if-2fa-enabled
2014-07-10 05:21:40 +08:00
2014-01-19 00:20:29 +08:00
### Filing a Pull Request on GitHub
2013-05-12 09:11:51 +08:00
Now go to *your* GitHub repository at
https://github.com/my-github-username/homebrew-cask, switch branch to your
2013-12-08 02:16:58 +08:00
topic branch and click the 'Pull Request' button. You can then add further
2013-05-12 09:11:51 +08:00
comments to your pull request.
Congratulations! You are done now, and your Cask should be pulled in or
otherwise noticed in a while.
2014-01-21 06:48:38 +08:00
### Squashing
If your pull request has multiple commits which revise the same lines of
code, it is better to [squash ](http://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.
2014-02-23 03:45:53 +08:00
2013-05-12 09:11:51 +08:00
## Cleaning up
2014-02-23 03:45:53 +08:00
After your Pull Request is away, you might want to get yourself back onto
`master` , so that `brew update` will pull down new Casks properly.
2013-05-12 09:11:51 +08:00
```bash
2014-05-09 08:02:48 +08:00
cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
2013-05-12 09:11:51 +08:00
git checkout master
```
Neat and tidy!
2014-02-23 03:45:53 +08:00
2014-01-19 00:20:29 +08:00
## Working On homebrew-cask Itself
2013-04-29 03:27:37 +08:00
2014-01-12 04:06:30 +08:00
If you'd like to hack on the Ruby code in the project itself, please
2014-02-23 03:45:53 +08:00
see [HACKING.md ](doc/HACKING.md ).
2013-04-29 03:27:37 +08:00
2013-05-12 09:11:51 +08:00
# <3 THANK YOU! <3