Prepare

Note: many of this step's substeps can be done in parallel.

Clone Checklist

Click on 'Create' ( below ) to copy this checklist to a new wiki page at Jetpack/SDK/Release_Checklist/VERSION (f.e. Jetpack/SDK/Release_Checklist/1.10), and choose people to fill the Release Manager (RM), Release Engineer (RE), Technical Lead (TL), and Documentation Lead (DL) roles. Use the checklist to track the status of the release.

If there are merge conflicts, you will need to resolve them first. In general, favor the version coming from the 'master' side, but keep an eye out for changes which somehow appeared on stabilization and *not* on master (perhaps these need to be cherry-picked to master). When done, compare the two trees to check for merge artifacts. The only differences should be in the minVersion/maxVersion fields, that will be changed next:

git diff master stabilization
# only differences should be in install.rdf, minVersion/maxVersion

Set JPCV (Jetpack Current Version) to the version for which you are starting the release process: what the stabilization branch will turn into. If 'cfx --version' on master at this point reports "1.2-dev-SOMETHING", then JPCV will be "1.2":

export JPCV=(UPCOMING VERSION)

Set JPNV (Jetpack Next Version) to the next-higher version identifier: what master will turn into the next time it is merged to stabilization, e.g. 1.3:

export JPNV=(NEXT VERSION)

Record an empty commit, to mark where master development switches from one release to the next:

git commit --allow-empty -m "branched off $JPCV, master is now destined to become $JPNV"

Add a development tag to master, so subsequent checkouts self-identify as headed towards the next release:

git tag $JPNV-dev

Do NOT change the Firefox minVersion/maxVersion compatibility identifiers on the master branch at this point. Master branch maintains compatibility with all current Firefox development channels, from release to mozilla-central (eg, from Firefox 9.0 through 12.0a1). When the next version of Firefox ships three weeks from now, THEN you can bump compatibility numbers (eg, to 10.0/13.0a1).

Push the changes to the canonical repository, and push the JPNV-dev tag too:

Product Planning

PR

Notify the Mozilla PR team (communications@mozilla.com).

PR likes to have the email, despite sitting in the planning meetings.

Spin Test Builds

To ensure the release meets our quality standards, spin test builds and distribute them to testers. Do this at least weekly during the stabilization period, spinning beta builds initially and one or more release candidate builds ultimately.

Clone the canonical repository, and enter the clone's working directory, and check out the stabilization branch:

Note: at present, the final release contains slightly different bits than the last release candidate: python-lib/cuddlefish/_version.py contains strings which are expanded by 'git archive' to include a tag name, which will be different in the rc and the final release. In addition, the unpacked directory name will be different.

Note: you may need to set the --binary flag to the location of the binary of Firefox against which you want to test the build.

Push the stabilization branch and the tag to the canonical repository:

git push origin stabilization ${JPNV}

Notify testers about the build via a post to the discussion forum. Have them run automated and manual tests (including submitting generated XPIs to the AMO test server) and report any bugs they discover. (Mention that testers should not try to submit add-ons built from the test builds to AMO, as it won't pass the validator.)

File a bug in the Builder component to get the test build uploaded to the -dev server.

Stabilize Codebase

Land stabilizing changes on the master branch.

Note: because of conflicts due to incompatible SDK and Firefox minVersion/maxVersion changes between the stabilization and master branches, do not land stabilizing changes on the stabilization branch and merge that branch to master. In the future, we may resolve the conflicts and do this.

Periodically generate a list of changes between the master and stabilization branches:

Note:--right-only shows only commits on master (on the right in the symmetric diff notation stabilization...master) that are not on stabilization; --cherry-pick omits equivalent commits; --no-merges excludes merge commits (it's usually better to cherry-pick only non-merge commits); --pretty shows useful info about each commit; and --reverse shows commits chronologically from older to newer (the same order in which you are most likely to cherry-pick them successfully).

Identify stabilizing changes landed on the master branch, and cherry-pick them to the stabilization branch:

git cherry-pick -x (REVISION ID)

Draft Release Announcement

To draft the post, access the blog's Wordpress admin page and go to Posts > Add New. Use previous release posts as a template for your new one. Make sure to include a <!-- more --> element to reduce the initial size of the post, and put the post into the developers, jetpack, general, and releases categories.

After drafting the post, share it with other folks who can help edit it, such as the project's marketing manager.

Note: don't publish the post in this step. That should happen in the Release step.

Write Release Notes

Release notes live on the wiki at /Labs/Jetpack/SDK/Release_Notes/(VERSION) (e.g. /Labs/Jetpack/SDK/Release_Notes/1.2). Create a page for the release notes, using the previous release's notes as a template, and include important information about the release in the notes. Mention the issues raised/addressed in each resolved bug that was fixed in the release and has been tagged with the relnote keyword. Also mention issues in each unresolved bug tagged with the relnote keyword.

Retrieve, unpack, and compare the last release candidate tarball against the
newly generated one. The only difference should be the embedded version
string. Since the same git revision referenced by both tags (JPRCV and JPFV), the
embedded git_refnames= string in the final tarball will contain both tags (JPRCV,JPFV).
The code that analyzes git_refnames= will prefer the shorter number-bearing string:

Merge the stabilization branch to the release branch: this should be a
fast-forward merge, because after each release, the release branch is merged
back into the stabilization branch:

git checkout release
git merge --ff-only stabilization

And push the final release tag and the release branch to the public repo:

git push origin ${JPFV} stabilization release

Update AMO Validator

Requirements: working checkout of AMO-validator & prerequisites. Please see the AMO Validator Readme for the gory details. We should fork the amo-validator repo and then for each release do the following:

Step 2: We issue a pull request to the mozilla/amo-validator and pester engage the AMO devs to accept our updated hash file, *and* add the tracking bug to the milestone for the next push. WARNING: unless the tracking bug is added to the milestone for the next push, the change will not be deployed!!!

Step 3: We do some testing on AMO's existing test infrastructure on allizom.com. The test should be essentially:

run the validator on xpi files that use the new version

ensure the validator does not raise errors on SDK core files.

Step 4: The changes are pushed with the regular Thursday AMO push.

Step 5: Once the AMO push is done, generate an XPI using the release candidate and validate it using AMO in order to verify that the validator has been updated and is working.

File Builder bug to push build

Once the Build has been blessed, we need to ensure that it is made available to Builder users as well. The process seems to be:

File a bug AMO with the 'Add-on Builder' component, to add the new version to production.

In a branch of your forked repo for Flightdeck, run these commands to add the new version as a submodule to the FlightDeck repo, then issue a pull request:

ensure that seanmonstr / zalun / arron accepts the pull request and tags it. IT can then take this tag and complete the deployment.

get IT[1] to run the 'add sdk' command on -dev, make sure things work. Also, stephend should be pinged to ensure tests pass on -dev with the new revision:

./manage.py add_core_lib addon-sdk-1.x --useversion=1.x

Schedule a push with IT[1] and push the site

Run the 'add sdk' command[1] in production

[1] It seems to help to assign a bug to IT (oremj specifically?) to get things done on IT's side, including a description of what needs to be done.

Update Latest Builds Redirect

Use a text editor like vi or emacs to update the /pub/mozilla.org/labs/jetpack/.htaccess file on ftp.mozilla.org to redirect the "latest" symlinks to the new release, making the content of the file look like this:

Update Latest Docs Redirect

Publish Release Announcement

Note: changes to the blog can take several hours to show up on the site because of server-side caching. To check that the post has been published, add "?(SOME UNIQUE STRING)" to the end of the URL, which bypasses the cache.

Notify Community

Notify the discussion forum about the release. Include a link to the release tag:

File a bug in the Builder component to get the new release pushed to the production Builder server.

Bask

Bask in the glow of the latest and greatest release!

Physically or virtually high-five or fist-jab contributors.

Review

Review the release process via a post-mortem, solicitation of feedback in the weekly meeting and discussion forum, and other methods as appropriate. Identify things that went well and we should continue to do, things that went badly that we should do differently next time, and parts of the process that have changed and for which this document needs to be updated. Make changes as appropriate.

Panic

Hot-Fixes are releases that are made directly on the "release" branch, rather
than the usual "stabilization" branch, and contain just one or two fixes
relative to the previous release. The Release Manager may decide to handle
critical bugs in e.g. 1.5 by creating a hot-fix release (1.5.1) instead of
waiting for the next scheduled release cycle (1.6).

To create a hot-fix release, start by creating a branch based off the most
recent release tag, cherry pick the important fix to it from master, make the
release, then merge back to stabilization.

The basic idea is that the "release" branch should always be a descendant of
the "stabilization" branch, so that normal releases (made on stabilization)
cause the "release" branch to be fast-forwarded to the new revision. The
normal release cycle takes care of this automatically: the code is developed
and tagged on stabilization, then "release" is moved forward to point to the
same revision. But since hotfixes are developed on "release", an extra
post-release merge step is necessary to bring "stabilization" up-to-date.

The general process is:

git clone git@github.com:mozilla/addon-sdk

cd addon-sdk

git checkout release

cherry-pick fixes from master to fix the bug, repeat until it works

git tag NEWRELEASE

use 'git archive' to create tarballs

upload tarballs (644 permissions!)

git checkout stabilization

git merge release (this may require conflict-resolution)

git push origin NEWRELEASE release stabilization

It may be easier to use a personal branch while developing the fix, to share
release candidates with others (especially when asking the original bug
submitter to validate the fix). In that case, the process will look something
like:

git clone MYGITHUBREPO ; cd MYREPO

git remote add official git@github.com:mozilla/addon-sdk

git fetch official

git checkout -b hotfix official/release

cherry-pick fixes, share RC builds

git push origin hotfix (to share code)

git checkout release

git merge --ff-only hotfix

git tag NEWRELEASE

make+upload tarballs (644 permissions!)

git checkout stabilization

git merge official/release (and resolve conflicts)

git push official NEWRELEASE release stabilization

git branch -D hotfix

After you make the hotfix, you'll need to get the hotfix pushed to Builder and update the AMO Validator, as detailed further up this page.