14 KiB

Raw Blame History

How To Contribute

So you want to contribute to the project. THIS IS GREAT NEWS! Seriously. We're all pretty happy about this. Here's how to get started:

Getting Set Up To Contribute
Adding a Cask
Testing Your New Cask
Finding a Home For Your Cask
Submitting Your Changes
Cleaning up

Getting Set Up To Contribute

Fork the repository in GitHub with the 'Fork' button
Add your GitHub fork as a remote for your homebrew-cask Tap

$ github_user='<my-github-username>'
$ cd "$(brew --prefix)"/Library/Taps/phinze-cask
$ git remote add "$github_user" "https://github.com/$github_user/homebrew-cask"

Adding a Cask

Making a Cask is easy: a Cask is a small Ruby file.

Here's a Cask for Alfred.app as an example. Note that you may repeat the link stanza as many times as you need, to create multiple links:

class Alfred < Cask
  url 'http://cachefly.alfredapp.com/Alfred_2.1.1_227.zip'
  homepage 'http://www.alfredapp.com/'
  version '2.1.1_227'
  sha256 'd19fe7441c6741bf663521e561b842f35707b1e83de21ca195aa033cade66d1b'
  link 'Alfred 2.app'
  link 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
end

Here is another Cask for Vagrant.pkg:

class Vagrant < Cask
  url 'https://dl.bintray.com/mitchellh/vagrant/Vagrant-1.4.3.dmg'
  homepage 'http://www.vagrantup.com'
  version '1.4.3'
  sha256 'e7ff13b01d3766829f3a0c325c1973d15b589fe1a892cf7f857da283a2cbaed1'
  install 'Vagrant.pkg'
  uninstall :script => { :executable => 'uninstall.tool', :input => %w[Yes] }
end

To get started, use the handy dandy brew cask create command.

$ brew cask create my-new-cask

This will open $EDITOR with a template for your new Cask. Note that the convention is that hyphens in the name indicate casing in the class name, so the Cask name 'my-new-cask' becomes MyNewCask stored in my-new-cask.rb. So running the above command will get you a template that looks like this:

class MyNewCask < Cask
  url ''
  homepage ''
  version ''
  sha256 ''
  link ''
end

Fill in the following stanzas for your Cask:

name	value
cask metadata	information about the Cask (required)
`url`	URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also URL Stanza Details)
`homepage`	application homepage; used for the `brew cask home` command
`version`	application version; give value of `'latest'` if versioned downloads are not offered
`sha256`	SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be omitted on unversioned downloads by substituting `no_checksum`. (see also Checksum Stanza Details)
artifact info	information about artifacts inside the Cask (can be specified multiple times)
`link`	relative path to a file that should be linked into the `Applications` folder on installation (see also Link Stanza Details)
`install`	relative path to `pkg` that should be run to install the application (see also Install Stanza Details)
`uninstall`	indicates what commands/scripts must be run to uninstall a pkg-based application (see also Uninstall Stanza Details)

Additional stanzas you might need for special use-cases:

name	value
`prefpane`	relative path to a preference pane that should be linked into the `~/Library/PreferencePanes` folder on installation
`colorpicker`	relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation
`qlplugin`	relative path to a QuickLook plugin that should be linked into the `~/Library/QuickLook` folder on installation
`font`	relative path to a font that should be linked into the `~/Library/Fonts` folder on installation
`widget`	relative path to a widget that should be linked into the `~/Library/Widgets` folder on installation (ALPHA: DOES NOT WORK YET)
`service`	relative path to a service that should be linked into the `~/Library/Services` folder on installation
`binary`	relative path to a binary that should be linked into the `/usr/local/bin` folder on installation
`input_method`	relative path to a input method that should be linked into the `~/Library/Input Methods` folder on installation
`screen_saver`	relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation
`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.
`caveats`	a string or Ruby block providing the user with Cask-specific information at install time (see also Caveats Details)

Additional special-use stanzas are listed at Optional Stanzas and Legacy Stanzas.

SourceForge URLs

SourceForge projects are a common way to distribute binaries, but they provide many different styles of URLs to get to the goods.

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.

If the "latest" URL does not point to a valid file for a Mac app, then we fall back to this format:

http://downloads.sourceforge.net/sourceforge/$PROJECTNAME/$FILENAME.$EXT

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.

Naming Casks

We try to maintain consistent naming so everything stays clean and predictable.

Find the Canonical Name of the Author's Distribution

Canonical Names of Apps

Start with the exact name of the Application bundle as it appears on disk, such as Google Chrome.app
Remove .app from the end
Translate the name into English if necessary
Remove from the end: "mac", "for mac", "for OS X". These terms are generally added to ports such as "MAME OS X.app". Exception: when the software is not a port, but "Mac" is an inseparable part of the name or branding, as in 'PlayForMac.app'
Remove from the end: hardware designations such as "for x86", "32-bit", "ppc".
Remove from the end: software framework names such as "Qt", "Gtk", "Wx", "Java", "Oracle JVM", etc. Exception: the framework is the product being Casked: java.rb.
Remove from the end: localization strings such as "en-US"
Pay attention to details, for example: "Git Hub" != "git_hub" != "GitHub"
If the result of that process is something unhelpful, such as Macintosh Installer, then just create the best name you can, based on the author's web page.

Canonical Names of `pkg`-based Installers

The Canonical Name of a pkg may be more tricky to determine than that of an App. If so, just create the best name you can, based on the author's web page.

Cask Name

A "Cask name" is the primary identifier for a package in our project. It's the string people will use to interact with this Cask on their system.

To get from the App's canonical name to the Cask name:

convert all letters to lower case
hyphens stay hyphens
spaces become hyphens
digits stay digits
delete any character which is not alphanumeric or hyphen
collapse a series of multiple hyphens into one hyphen
delete a leading hyphen
a leading digit gets spelled out into English: 1password becomes onepassword

Casks are stored in a Ruby file matching their name.

Cask Class

Casks are implemented as Ruby classes, so a Cask's "class" needs to be a valid Ruby class name.

When going from a Cask's name to its class name:

UpperCamelCased
wherever a hyphen occurs in the Cask name, the class has a case change
invalid characters are replaced with English word equivalents

Cask Naming Examples

These illustrate most of the naming rules:

Canonical App Name	Cask Name	Cask Class
Audio Hijack Pro	`audio-hijack-pro`	`AudioHijackPro`
VLC	`vlc`	`Vlc`
BetterTouchTool	`bettertouchtool`	`Bettertouchtool`
iTerm2	`iterm2`	`Iterm2`
Akai LPK25 Editor	`akai-lpk25-editor`	`AkaiLpk25Editor`
Sublime Text 3	`sublime-text3`	`SublimeText3`
1Password	`1password`	`Onepassword`

Archives With Subfolders

When a downloaded archive expands to a subfolder, the subfolder name must be included in the link value.

Example:

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:
```
link 'TexmakerMacosxLion/texmaker.app'
```

Indenting

All Casks and code in the homebrew-cask project should be indented using two spaces (never tabs).

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 to fix it.

If everything looks good, you'll also want to make sure your Cask passes audit with

brew cask audit my-new-cask --download

If your application and homebrew-cask do not work well together, feel free to file an issue after checking out open issues.

Finding a Home For Your Cask

We maintain separate Taps for different types of binaries.

Latest Stable Versions

Latest stable versions live in the main repository at phinze/homebrew-cask. 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!

When an App is only available as a Beta, or in cases where a "Beta" has become the general standard, then an "unstable" version can go into the main repo.

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. Nightly builds always go in caskroom/homebrew-versions.

Unofficial Builds

When an App developer does not offer a binary download, please submit the Cask to caskroom/homebrew-unofficial. For a location to host unofficial builds, contact our sister project alehouse.

Fonts

Font Casks live in the caskroom/homebrew-fonts repository. See the font repo CONTRIBUTING.md for details.

Submitting Your Changes

Hop into your Tap and check to make sure your new Cask is there:

$ cd "$(brew --prefix)"/Library/Taps/phinze-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:

$ 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 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

Pushing

Push your changes to your GitHub account:

$ github_user='<my-github-username>'
$ git push "$github_user" my-new-cask

Filing a Pull Request on GitHub

Now go to your GitHub repository at https://github.com/my-github-username/homebrew-cask, switch branch to your topic branch and click the 'Pull Request' button. You can then add further comments to your pull request.

Congratulations! You are done now, and your Cask should be pulled in or otherwise noticed in a while.

Squashing

If your pull request has multiple commits which revise the same lines of code, it is better to squash 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.

Cleaning up

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.

cd "$(brew --prefix)"/Library/Taps/phinze-cask
git checkout master

Neat and tidy!

Working On homebrew-cask Itself

If you'd like to hack on the Ruby code in the project itself, please see HACKING.md.

14 KiB Raw Blame History