Skip to content

Latest commit

 

History

History
420 lines (288 loc) · 15.4 KB

CONTRIBUTING.md

File metadata and controls

420 lines (288 loc) · 15.4 KB
Raw

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

  1. Fork the repository in GitHub with the 'Fork' button
  2. Add your GitHub fork as a remote for your homebrew-cask Tap
$ github_user='<my-github-username>'
$ cd "$(brew --repository)"/Library/Taps/caskroom/homebrew-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.

Examples

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

cask :v1 => 'alfred' do
  version '2.3_264'
  sha256 'a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92'

  url 'https://cachefly.alfredapp.com/Alfred_2.3_264.zip'
  name 'Alfred'
  homepage 'http://www.alfredapp.com/'
  license :freemium

  app 'Alfred 2.app'
  app 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
end

Here is another Cask for Unity.pkg:

cask :v1 => 'unity' do
  version '4.5.4'
  sha256 '6fb72bfacf78df072559dd9a024a9d47e49b5717c8f17d53f05e2fc74a721876'

  url 'http://netstorage.unity3d.com/unity/unity-4.5.4.dmg'
  name 'Unity'
  name 'Unity3D'
  homepage 'http://unity3d.com/unity/'
  license :commercial

  pkg 'Unity.pkg'

  uninstall :pkgutil => 'com.unity3d.*'
end

And here is one for Firefox.app. 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 an unversioned download URL is available:

cask :v1 => 'firefox' do
  version :latest
  sha256 :no_check

  url 'https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US'
  name 'Firefox'
  homepage 'https://www.mozilla.org/en-US/firefox/'
  license :mpl

  app 'Firefox.app'
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:

$ "$(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:

$ "$(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.

The brew cask create Command

Once you know the token, create your Cask with the handy-dandy brew cask create command.

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

cask :v1 => 'my-new-cask' do
  version ''
  sha256 ''

  url ''
  name ''
  homepage ''
  license :unknown

  app ''
end

Cask Stanzas

Fill in the following stanzas for your Cask:

name value
version application version; give the value :latest if 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 also Checksum Stanza Details)
url URL to the .dmg/.zip/.tgz file that contains the application (see also URL Stanza Details)
name the full and proper name defined by the vendor, and any useful alternate names (see also Name Stanza Details)
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 also License Stanza Details)
app relative path to an .app bundle that should be linked into the ~/Applications folder on installation (see also App Stanza Details)

Other commonly-used stanzas are:

name value
pkg relative path to a .pkg file containing the distribution (see also Pkg Stanza Details)
uninstall procedures to uninstall a Cask. Optional unless the pkg stanza is used. (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
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
suite relative path to a containing directory that should be linked into the ~/Applications folder on installation
container :nested => 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 Stanza Details)

Even more 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, if the app is Mac-exclusive (otherwise a command-line download defaults to the Windows version):

http://sourceforge.net/projects/$PROJECTNAME/files/latest/download

This lets SourceForge pick the best mirror 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

Or, if it’s from SourceForge.JP:

http://$STRING.sourceforge.jp/$PROJECTNAME/$RELEASEID/$FILENAME.$EXT

$STRING is typically of the form dl or $USER.dl.

Personal Hosting Such as Dropbox

URLs from dropbox.com or cl.ly/cloudapp.com are not readily distinguishable as being controlled by the original software vendor. These URLs should be used only when given as such on the official project website.

Also make sure to give the URL for the binary download itself, rather than a preview page. (See https://www.dropbox.com/help/201/en.)

Some Providers Block Command-line Downloads

Some hosting providers actively block command-line HTTP clients (example: FossHub). Such URLs cannot be used in Casks.

Vendor URLs Are Preferred

When possible, it is best to use a download URL from the original developer or vendor, rather than an aggregator such as macupdate.com.

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 and 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 cask_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:

  • 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 app stanza should include the subfolder as a relative path:

    app '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 caskroom/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 an unstable version (e.g. beta, nightly), or in cases where such a version is 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.

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.

Unofficial, Vendorless, or Walled Builds

When an App developer does not offer a binary download, the binary doesn't have an official vendor, or the download URL is both behind a registration wall and served from an unofficial host, 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 --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:

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

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

If you are using GitHub two-factor authentication 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

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 --repository)"/Library/Taps/caskroom/homebrew-cask
git checkout master

Neat and tidy!

<3 THANK YOU! <3