Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
403 lines (283 loc) · 15.1 KB

CONTRIBUTING.md

File metadata and controls

403 lines (283 loc) · 15.1 KB

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

Examples

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

The brew cask create Command

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

Cask Stanzas

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)

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:

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: version numbers or incremental release designations such as "alpha", "beta", or "release candidate". Strings which distinguish different capabilities or codebases such as "Community Edition" are currently accepted. Exception: when a number is not an incremental release counter, but a differentiator for a different product from a different vendor: iterm2.rb.
  • If the version number is arranged to occur in the middle of the App name, it should also be removed. Example: IntelliJ IDEA 13 CE.app.
  • 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 a pkg installs an App, then use that App name with the rules above. If not, 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.

<3 THANK YOU! <3