Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CONTRIBUTING.md: Adding unversioned Cask info #6145

Merged
merged 1 commit into from
Sep 11, 2014
Merged

CONTRIBUTING.md: Adding unversioned Cask info #6145

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,20 @@ class Vagrant < Cask
end
```

And here is one for Firefox; 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 version is available). This combination of `version 'latest'` and `sha256 :no_check` is currently the preferred mechanism when an unversioned download link is available:

```ruby
class Firefox < Cask
version 'latest'
sha256 :no_check

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

link 'Firefox.app'
end
```

### Naming the Cask

We try to maintain consistent naming for the benefit of our users.
Expand Down Expand Up @@ -119,7 +133,7 @@ Fill in the following stanzas for your Cask:
| __cask metadata__ | information about the Cask (required)
| `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))
| `homepage` | application homepage; used for the `brew cask home` command
| `version` | application version; give value of `'latest'` if versioned downloads are not offered
| `version` | application version; give the value `'latest'` if an unversioned download is available
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we could have this be a more neutral example (in preparation for the future). Something like “application version; give value of 'latest' if using an unversioned download”.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But that's specifically what screwed me up. Making no explicit recommendation would lead me and other potential newbie contributors to think version 'latest'/sha256 :no_check is an option for the sake of speed and/or laziness and to be avoided whenever possible.

Right now, if there are both versioned and unversioned downloads available, the policy as I've now been illuminated on is to prefer the unversioned download. The fact that this will change in the future is irrelevant, IMO, since a contributor isn't going to take the time to delve into all the tickets in addition to reading CONTRIBUTING.md. (And if they do, they may still come to the wrong conclusion as I did.)

Feel free to open an issue against me, now, to fix this line once the future arrives.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Let’s leave it.

| `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))
| __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](doc/CASK_LANGUAGE_REFERENCE.md#link-stanza-details))
Expand Down Expand Up @@ -323,14 +337,15 @@ 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.
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:

Expand Down