diff --git a/developer/bin/generate_changelog b/developer/bin/generate_changelog index 628f9ff590..117c4513e6 100755 --- a/developer/bin/generate_changelog +++ b/developer/bin/generate_changelog @@ -36,6 +36,7 @@ CODE_PATHS = %w[ bin developer lib + spec test brew-cask.rb Rakefile @@ -236,12 +237,17 @@ def header - N total Casks * __Features__ - none +* __Breaking Changes__ + - none * __Fixes__ - none +* __Internal Changes__ + - none * __Documentation__ - N doc commits since ... -* __Breaking Changes__ - - none +* __Contributors__ + - N new contributors since ... + - N total contributors EOT end diff --git a/developer/bin/project_stats b/developer/bin/project_stats index 02f141df55..3d19f99493 100755 --- a/developer/bin/project_stats +++ b/developer/bin/project_stats @@ -19,7 +19,7 @@ shopt -s nocasematch # case-insensitive regular expressions # these paths relative to project root declare -a cask_paths=(Casks) -declare -a code_paths=(bin developer lib test brew-cask.rb Rakefile Gemfile Gemfile.lock .travis.yml .gitignore) +declare -a code_paths=(bin developer lib spec test brew-cask.rb Rakefile Gemfile Gemfile.lock .travis.yml .gitignore) declare -a doc_paths=(doc LICENSE "*.md") end_object="HEAD" diff --git a/doc/RELEASING.md b/doc/RELEASING.md index c441448468..fd5d18d08a 100644 --- a/doc/RELEASING.md +++ b/doc/RELEASING.md @@ -17,36 +17,47 @@ tag that exists and/or calculate the proposed next release tag. Docs are at ## 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. +This is partially scripted now. The most time-consuming step is editing the +changelog. + +1. Be running on a checkout of `master` which is up to date and `git status` + clean: + ```bash + $ git checkout master && git status + ``` -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 +3. Pull in the latest `master` + + ```bash + $ git pull https://github.com/caskroom/homebrew-cask master + ``` + +4. 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 + If the newly-compiled man page has no changes 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: +5. Do a `git log` to see what changed since the last release. You can scope it + to only code changes: ```bash - $ git log "$(./developer/bin/get_release_tag)"..HEAD -- lib test developer bin Gemfile Gemfile.lock Rakefile brew-cask.rb + $ git log "$(./developer/bin/get_release_tag)"..HEAD -- lib spec 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, +6. Decide whether to bump the minor or patch field in the next release tag, based on whether or not features were added. For a feature release, run the shell command: @@ -57,29 +68,29 @@ written down than floating in a brain somewhere. ```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 +7. Make sure the value in `$NEW_RELEASE_TAG` is what you want. +8. 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 + except that the Ruby version should lack the leading `v` character. +9. 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 +10. 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. +11. 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`, +12. Make a commit on `master` with the modifications to `doc/CHANGELOG.md`, `lib/cask/version.rb`, and/or `doc/man/brew-cask.1`: ```bash @@ -87,56 +98,58 @@ written down than floating in a brain somewhere. $ git commit -m "cut $NEW_RELEASE_TAG" ``` -12. Tag that commit. Make certain to provide a `-m` message so that we get +13. 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 +14. Push that commit and the tag ```bash - $ git push https://github.com/caskroom/homebrew-cask master && git push https://github.com/caskroom/homebrew-cask tag "$NEW_RELEASE_TAG" + $ git push https://github.com/caskroom/homebrew-cask master && git push https://github.com/caskroom/homebrew-cask tag "$NEW_RELEASE_TAG" && echo "new release $NEW_RELEASE was successfully pushed" ``` - -14. Unset the shell variable `$NEW_RELEASE_TAG`; you don't need it anymore. + If you don't see a success message, that probably means someone updated + master while you were working on the changelog. You must pull and resolve. +15. Open your browser to . + Click the link for your newly-pushed tag. On the following page, click the + `Edit tag` button in the top right corner. This opens a page with a form + for the release information and changelog. +16. On the release page + * If the `Tag version` field does not auto-fill, manually select the tag + you just created (shell variable `$NEW_RELEASE_TAG`). + * Paste the Markdown summary for the new release from `doc/CHANGELOG.md` + into the main textarea. + * The `## ` heading line from the changelog should not be + included in the pasted text. + * The `Release title` field may be left blank. +17. Click `Publish Release`. +18. Unset the shell variable `$NEW_RELEASE_TAG`; you don't need it anymore: ```bash $ unset NEW_RELEASE_TAG ``` -15. Open your browser to . - Click the link for your newly-pushed tag. On the following page, click the - `Edit tag` button in the top right corner. The next page contains a form - for the release information and changelog. -16. On the release page, if the `Tag version` field does not auto-fill, manually - select the tag you just created. -17. Paste the markdown summary for the new release from `doc/CHANGELOG.md` - into the main textarea. -18. The `## ` heading line from the changelog should not be - included in the pasted text. -19. The `Release title` field may be left blank. -20. Click `Publish Release`. -21. Announce the release on IRC. -22. Respond to any pending GitHub issues which may be resolved after users +19. Announce the release on IRC. +20. Respond to any pending GitHub issues which may be resolved after users upgrade. -23. Rejoice! Have a :cookie:. +21. 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. +The way `brew update` works, users will always be tracking `HEAD` in their +Tap. This means that the latest updates to Casks are always propagated +ahead of code releases. 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! ## Notes -* In step number 13: +* In steps 3 and 14: * The full URL is given for the repo because that does not change depending on your local `.git/config`. Equivalent commands may be @@ -144,5 +157,5 @@ In general: go easy on the users! * We push the commits *before* pushing the tag to ensure that there are no conflicts. The default behavior of `git push --follow-tags` is to push - tags to the public repo before commits, which lead to the "lost" tag + tags to the public repo before commits, which caused the "lost" tag v0.39.0.