updates to release process after v0.40.0

2026-08-05 13:43:24 -07:00 · 2014-09-08 11:24:38 -04:00
parent 92e15b4a91
commit b93206093a
3 changed files with 69 additions and 50 deletions
@@ -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

@@ -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"

@@ -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 <https://github.com/caskroom/homebrew-cask/releases> .
+    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 `## <version number>` 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 <https://github.com/caskroom/homebrew-cask/releases> .
-    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 `## <version number>` 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.