mirror of
https://github.com/donl/homebrew-cask-versions.git
synced 2026-07-17 06:16:47 -06:00
134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
# Release Standards
|
|
|
|
Here's where we document how homebrew-cask is released.
|
|
|
|
## Versioning
|
|
|
|
We attempt to follow [Semantic Versioning](http://semver.org/) as much as
|
|
possible.
|
|
|
|
Since we are still pre-1.0, this essentially means that we bump the PATCH
|
|
number when we fix bugs, and we bump the MINOR number when we add features.
|
|
Pretty simple.
|
|
|
|
The script `./developer/bin/get_release_tag` can tell you the latest release
|
|
tag that exists and/or calculate the proposed next release tag. Docs are at
|
|
`get_release_tag -help`.
|
|
|
|
## Release Process
|
|
|
|
We'll get this fully scripted someday, but until then it's better to have it
|
|
written down than floating in a brain somewhere.
|
|
|
|
1. Be running on a checkout of master which is up to date and `git status` clean.
|
|
2. `cd` to the project root.
|
|
|
|
```bash
|
|
$ cd "$(git rev-parse --show-toplevel)"
|
|
```
|
|
|
|
3. Compile the man page and check the result by running
|
|
|
|
```bash
|
|
$ ./developer/bin/generate_man_pages; git --no-pager diff ./doc/man/brew-cask.1
|
|
```
|
|
If the newly-compiled man page has no updates other than the datestamp, you
|
|
may wish to discard the changes as follows:
|
|
|
|
```bash
|
|
$ git checkout -- ./doc/man/brew-cask.1 # discard changes
|
|
```
|
|
|
|
4. Do a `git log` to see what changed since the last release. You can scope it
|
|
to just pick up code changes, like this:
|
|
|
|
```bash
|
|
$ git log "$(./developer/bin/get_release_tag)"..HEAD -- lib test developer bin Gemfile Gemfile.lock Rakefile brew-cask.rb
|
|
```
|
|
|
|
5. Decide whether to bump the minor or patch fields in the next release tag,
|
|
based on whether or not features were added. For a feature release, run the
|
|
shell command:
|
|
|
|
```bash
|
|
$ export NEW_RELEASE_TAG="$(./developer/bin/get_release_tag -next)"; echo "$NEW_RELEASE_TAG"
|
|
```
|
|
or for a patch release, add `-patch` to the command:
|
|
```bash
|
|
$ export NEW_RELEASE_TAG="$(./developer/bin/get_release_tag -next -patch)"; echo "$NEW_RELEASE_TAG"
|
|
```
|
|
6. Make sure the value in `$NEW_RELEASE_TAG` is what you want.
|
|
7. Bump the `HOMEBREW_CASK_VERSION` string which is stored in the file
|
|
`lib/cask/version.rb`:
|
|
|
|
```bash
|
|
$ ./developer/bin/bump_version "$NEW_RELEASE_TAG"
|
|
```
|
|
The version string in the Ruby code should match `$NEW_RELEASE_TAG`,
|
|
except that the leading `v` character should be removed.
|
|
8. Generate a draft changelog for the new release by running
|
|
|
|
```bash
|
|
$ ./developer/bin/project_stats release >| /var/tmp/draft_release_changelog.md
|
|
$ ./developer/bin/generate_changelog >> /var/tmp/draft_release_changelog.md
|
|
```
|
|
|
|
9. Edit the draft changelog, following the patterns used in `doc/CHANGELOG.md`.
|
|
Some of the items for the changelog should be extracted from the statistics
|
|
section at the start of the file, after which the statistics section can be
|
|
deleted.
|
|
10. When complete, insert the new release changelog near the beginning of
|
|
`doc/CHANGELOG.md`, just after the first line.
|
|
11. Make a commit on `master` with the modifications to `doc/CHANGELOG.md`,
|
|
`lib/cask/version.rb`, and/or `doc/man/brew-cask.1`:
|
|
|
|
```bash
|
|
$ git add doc/CHANGELOG.md lib/cask/version.rb doc/man/brew-cask.1
|
|
$ git commit -m "cut $NEW_RELEASE_TAG"
|
|
```
|
|
|
|
12. Tag that commit. Make certain to provide a `-m` message so that we get
|
|
an annotated tag in the git history:
|
|
|
|
```bash
|
|
$ git tag -m "$NEW_RELEASE_TAG" "$NEW_RELEASE_TAG"
|
|
```
|
|
|
|
13. Push that commit and the tag:
|
|
|
|
```bash
|
|
$ git push --follow-tags
|
|
```
|
|
Or, depending on your git configuration, you might need to append
|
|
`<repository> <refspec>` to the above command, for example:
|
|
|
|
```bash
|
|
$ git push --follow-tags upstream master
|
|
```
|
|
|
|
14. Unset the shell variable `$NEW_RELEASE_TAG`; you don't need it anymore.
|
|
|
|
```bash
|
|
$ unset NEW_RELEASE_TAG
|
|
```
|
|
|
|
15. Open your browser to <https://github.com/caskroom/homebrew-cask/releases> .
|
|
Click the link for your newly-pushed tag. Click the "Edit Tag" button in
|
|
the top right corner of that page.
|
|
16. Paste the markdown summary from `doc/CHANGELOG.md` into the textarea on that
|
|
page. The `## <version number>` heading line from the changelog should
|
|
not be included. The `Release title` field on the GitHub web form may
|
|
be left blank.
|
|
17. Click "Publish Release".
|
|
18. Rejoice! Have a :cookie:.
|
|
|
|
## Things to Consider
|
|
|
|
The way `brew update` works, users will always be tracking `HEAD` in their tap.
|
|
This means that the latest updates to Casks are going to trickle out
|
|
immediately after push. This means there are times when we need to be
|
|
thoughtful about how we push out new or breaking functionality. As a pre-1.0
|
|
project we can still break backwards compatibility, but sometimes there might
|
|
be decisions we can make about releasing to make things easier on our users.
|
|
|
|
In general: go easy on the users!
|