Introduction
In the interest of raising our bus factor, this page documents our process for releasing a new version of Growl.
Advancing the version number
In the Growl repository (usually development):
- cd Release
- Edit the Makefile and increase the version number there.
- make version
- hg ci
Producing a release
Increase the version number in development first.
- cd into your clone of the growl-stable repository and hg pull.
- Pull from your clone of the growl-development repository into your growl-stable repository, specifying the desired branch (e.g., hg pull ../growl-development#branchname).
- Ensure the checkout is clean. You must have absolutely no unignored output files lying around. One easy way to clean your checkout is: hg up -C null && rm -R *; hg up -C branchname
- cd Release
- make (or, for GrowlMail, make release-growlmail )
- open build (Two or three important files are in this folder: The end-user disk image, the SDK disk image only, and the dSYM-bundles archive.)
- Copy the disk image somewhere and open it. Install Growl and every Extra and make sure it works.
- Tag the version: hg tag <version-number>. For example, hg tag 1.2.2. Tag GrowlMail versions as, for example, GrowlMail-1.2.4. Tag betas (as, e.g., 1.2.2b1 or GrowlMail-1.2.4b1) as well as final releases.
- Pull the tag changeset back to development and push both to our server.
- Copy or move the three files to your website checkout, in htdocs/files.
- Export a source archive. From your stable repository, hg archive -r1.2.2 someplace/Growl-1.2.2-src && cd someplace && tar cjf Growl-1.2.2-src.tbz Growl-1.2.2-src . Don't use -t tbz — that includes the “.tbz” suffix in the name of the archive's root directory.
- Copy or move the source archive to your website checkout, in htdocs/files/source .
- Open Transmit and upload all four files to CacheFly. You should probably upload the user dmg first, so that it has time to be distributed throughout the CDN while the other files upload.
- Also upload them to Google Code Hosting. Note tags and title formats used on existing versions.
- Begin writing the version history. Assuming you've done at least one beta, you can borrow and merge entries from the beta history. You may wish to review the list of tickets to ensure nothing was missed.
- On GCH, mark the previous version's files—including source archive—as Deprecated. Remove the Featured tag from those old files that have it.
- Update the pages on the website that need to be updated (see below) and commit.
- svn add the files in your website checkout and commit them in a separate commit.
- After the website updates, send an announcement to Growl-announcements and Growl discuss. Include the relevant product page (currently either http://growl.info/ or http://growl.info/growlmail/) or beta page (that + beta.html) at the top of the message; follow with selected items from the version history that will be of interest to users. (Exclude things like build fixes.)
- Also announce the update on @GrowlMac on Twitter.
Version history entry format
Entries in our version histories look like this:
<div class="version">
<h3>1.2.2¹ ([1ced1aac32db²])</h3>
<div class="changes">
<h4>Everything³</h4>
<ul>
<li>Changed the icon (<a href="http://growl.info/hg/growl/rev/dc159472ca8d">[dc159472ca8d]</a>, <a href="http://growl.info/hg/growl/rev/82c0df71cfc2">[82c0df71cfc2]</a>, <a href="http://growl.info/hg/growl/rev/42ae97755d08">[42ae97755d08]</a>⁴)</li>
</ul>
⋮
</div>
</div>
- Version number. For betas, this looks like “1.2.2b1”.
- Revision number of the tagged revision. “hg log -r1.2.2” should identify this revision.
- Module that was changed. “Everything”, “Growl”, “Growl.framework”, or the name of an Extra.
- I (prh) enter these as simply “[revision]”, then apply the following substitution in TextWrangler (where I have it saved):
Find: \[?([0-9a-f]{12})\]?
Replace: <a href="http://growl.info/hg/growl/rev/\1">[\1]</a>Note that this will also match entries so expanded, so you will need to step through matches one at a time—do not use Replace All.
Pages on the website to update
- The beta page, when releasing a beta or beginning or ending a beta phase
- The version history (see above)
- includes/definitions.php, which gives the version number and user dmg links (and, for GrowlMail, the source archive link)
- version-current.xml, which is used by the Growl non-Sparkle updater
When ending beta testing, use svn log beta.html to find the last non-beta version of the beta page, and svn cat -r[REV] beta.html > beta.html (where [REV] is the last non-beta version) to replace the current version with that version such that you can commit the change.