Jetpack/Release Process: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
(96 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= Overview =
This document describes the process by which versions of the Add-on SDK are released.  For information about the process by which versions of the SDK are developed, see [[Jetpack/Development Process]].


Jetpack SDK development happens in roughly four week cycles, as described in [[Labs/Jetpack/Process|Development Process]], each of which culminates in stabilization and release of the codebase. This document describes the release process.
= Prepare =


The overall process is:
{{note|many of this step's substeps can be done in parallel.}}


# freeze development
== Clone Checklist ==
# prepare to release
#* notify relevant parties
#* build/test release candidate(s)
#* create marketing/PR/evangelism materials
# thaw development
# release
# feel good
# review the process


In general, we freeze on a Tuesday night at 11:59pm, make the first release candidate available the next day, spend about a week stabilizing the code and preparing the materials, and release the following Wednesday. To ensure that the code is well-baked, we release no sooner than a week after the first candidate and two days after the last one.
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.


We use numerically consecutive versions to denote major releases (0.1, 0.2, etc.). Development cycles use the version of the next release followed by "pre" (0.1pre before 0.1, 0.2pre before 0.2, etc.). Release candidates use the final release version internally (i.e. in all code, documentation, and other files inside the package) and that version followed by "rc" and the number of the candidate (0.1rc1, 0.1rc2, etc.) in references external to the package (e.g. in the names of the packages).
<createbox>
align=left
type=create
preload=Jetpack/SDK/TEMPLATE/Release_Checklist
default=1.xx
prefix=Jetpack/SDK/Release_Checklist/
</createbox>


The rest of this document describes each step in more detail. When following these steps to release a new version, track the non-trivial work being done by filing a meta-bug for the release that depends on individual bugs for each discrete task.
The template for this form is [[Jetpack/SDK/TEMPLATE/Release_Checklist|here]].


= Freeze Development =
==Past SDK Release checklists==


Freezing is easy. Just notify Jetpack code contributors that development has been frozen via a post to the forum. The post should specify that the only changes that can be committed to the repository until it thaws are release blockers and low risk fixes that have been approved by the release drivers.
{{Special:PrefixIndex/Jetpack/SDK/Release_Checklist}}


Kill two birds with one stone!  Use the post to notify the forum about the release, as specified in Prepare to Release > Notify Relevant Parties > Notify Forum below.
== Merge Master to Stabilization ==


= Update Credits =
Clone the canonical repository, and enter the clone's working directory:


Update the Credits page at static-files/md/dev-guide/credits.md to include the names of folks who have contributed to the project since the last release.
git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk


= Prepare to Release =
Merge the master (development) branch to the stabilization branch:


Preparing to release involves doing three different sets of things, which can be done in parallel:
git checkout stabilization
git merge --no-commit master
# resolve conflicts, if any (don't resolve install.rdf yet!)
git commit -m "merge master into stabilization to start the N.N release cycle"


* file tracking bugs
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:
* notify relevant parties
* build/test release candidate(s)
* create marketing/PR/evangelism materials


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


File a bug to track code blockers of the release and another to track the overall release.
Change the Firefox minVersion/maxVersion compatibility identifiers on the stabilization branch per the [[Jetpack/Development Process]].


* [https://bugzilla.mozilla.org/enter_bug.cgi?bug_status=ASSIGNED&assigned_to=myk@mozilla.org&cc=dietrich%40mozilla.com&comment=This%20bug%20tracks%20code%20blockers%20for%20the%20Add-on%20SDK%20X.X%20release.%20%20Ping%20Myk%20or%20Dietrich%2C%20or%20comment%20here%20in%20this%20bug%2C%20to%20nominate%20a%20bug%20to%20block%20the%20release.&product=Add-on%20SDK&component=General&op_sys=All&priority=--&rep_platform=All&short_desc=X.X%20release%20blocker%20bugs code blockers bug template]
Commit the changes:
* [https://bugzilla.mozilla.org/enter_bug.cgi?bug_file_loc=https%3A%2F%2Fwiki.mozilla.org%2FLabs%2FJetpack%2FSDK%2FX.X%2FRelease&bug_status=ASSIGNED&cc=dietrich%40mozilla.com&comment=We%20should%20release%20Add-on%20SDK%20X.X.%20%20Use%20this%20bug%20to%20track%20tasks%20that%20need%20to%20be%20done%20to%20release%20the%20product%2C%20like%20spinning%20candidate%20builds%20and%20publishing%20a%20blog%20post%20about%20it.%20%20Use%20bug%20(code%20blockers%20bug%20number)%20to%20track%20code%20blockers%20for%20the%20release.&product=Add-on%20SDK&component=General&op_sys=All&rep_platform=All&short_desc=release%20Add-on%20SDK%20X.X&assigned_to=myk@mozilla.org&dependson=(code%20blockers%20bug%20number) release bug template]


== Notify Relevant Parties ==
git commit -a -m"update Firefox minVersion/maxVersion to anticipated current/next versions of Firefox"
 
Change back to the master branch:
 
git checkout master
 
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:


=== Notify Forum ===
git tag $JPNV-dev


Notify Jetpack participants in the [http://groups.google.com/group/mozilla-labs-jetpack discussion forum] about the release. Mention the tentative release date, tracking bug, and release notes. Notify the forum again if the release date changes and when each release candidate becomes available.
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).  


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


Notify Jetpack ambassadors about the release. Include the same information in the notice sent to the discussion forum.
git push origin master stabilization
git push --tags origin


=== Notify PR and Engagement ===
== File Tracking Bug ==


Contact the Mozilla PR team (press@mozilla.com) as well as the folks in charge of Jetpack engagement on the Engagement team (currently Mayumi Matsuno and Dan Horner) and let them know about the release by emailing them. Tell them the tentative release date. Note whether this is just another in the regular monthly sequence of releases or a major milestone (which determines whether or not the release is likely to be a PR event).
File a bug to track the release using [https://bugzilla.mozilla.org/enter_bug.cgi?assigned_to=jgriffiths@mozilla.com&bug_file_loc=https://wiki.mozilla.org/Jetpack/SDK/Release_Checklist/X.X&bug_status=ASSIGNED&comment=We%20should%20release%20Add-on%20SDK%20X.X.%0D%0A%0D%0AUse%20this%20bug%20to%20track%20release%20blockers%20and%20the%20release%20checklist%20%3Chttps%3A%2F%2Fwiki.mozilla.org%2FJetpack%2FSDK%2FRelease_Checklist/X.X%3E%20to%20track%20release%20tasks.%0D%0A&op_sys=All&product=Add-on%20SDK&rep_platform=All&short_desc=release%20Add-on%20SDK%20X.X this release tracking bug template].


Notify them again if anything changes (f.e. the release date).
== Notify Relevant Parties ==


=== Notify Product Delivery Team ===
=== Community ===


Notify the product delivery team about the release by adding a summary of its goals, status of the release candidates, and tentative release date to the [[Firefox/DeliveryMeetings|weekly meeting]] notes. Attend the weekly meeting and talk about the release.
Notify project participants in the [http://groups.google.com/group/mozilla-labs-jetpack discussion forum]. Mention the tentative release date, and reference the tracking bug and release checklist.


=== Notify IT ===
=== Product Planning ===


IT is responsible for pushing changes to the website (including new versions of the documentation) to production, and they should be notified in advance that such changes are forthcoming, even though they don't actually push the changes until the day of the release.
Notify product planners via their [[Firefox/Planning|weekly meeting]].


To notify them, file an IT request ([https://bugzilla.mozilla.org/enter_bug.cgi?blocked=(release%20bug%20number)&bug_status=NEW&cc=zandr%40mozilla.com&comment=We%20are%20now%20stabilizing%20the%20Add-on%20SDK%20source%20tree%20in%20preparation%20for%20the%20release%20of%20Add-on%20SDK%20X.X.%20%20When%20it%20is%20time%20to%20release%2C%20the%20corresponding%20changes%20to%20its%20website%20should%20be%20pushed%20to%20production%2C%20including%3A%0a%0a1.%20pushing%20the%20new%20version%27s%20docs%20to%20the%20website%3B%0a2.%20updating%20the%20%2Fsdk%2Flatest%2Fdocs%2F%20redirect%20to%20point%20to%20the%20new%20version%27s%20docs%3B%0a3.%20pushing%20the%20files%20in%20the%20changeset%20tagged%20%22website-production%22%20in%20the%20%22website%22%20subdirectory%20in%20the%20repository%20https%3A%2F%2Fhg.mozilla.org%2Flabs%2Fjetpack%20to%20the%20production%20server.%0a%0aNote%3A%20this%20work%20should%20not%20be%20done%20until%20the%20day%20of%20the%20release.%20%20The%20tentative%20release%20date%20is%20currently%20Wednesday%2C%20(Month%20and%20Date).&component=Server%20Operations%3A%20Web%20Content%20Push&op_sys=All&product=mozilla.org&rep_platform=All&short_desc=push%20Add-on%20SDK%20X.X%20website%20changes%20to%20production IT request bug template]), cc:ing ":zandr", to have the website changes pushed to production, including:
=== PR ===


# pushing the new version's docs to the website;
Notify the Mozilla PR team (communications@mozilla.com).
# updating the /sdk/latest/docs/ redirect to point to the new version's docs;
# pushing the files in the changeset tagged "website-production" in the "website" subdirectory in the repository https://hg.mozilla.org/labs/jetpack to the production server.


Make sure to note that the work shouldn't be done until the day of the release, specify the tentative release date, and update it if it changes.
PR likes to have the email, despite sitting in the planning meetings.


== Build/Test Release Candidate(s) ==
== Spin Test Builds ==


In order to make sure a release meets our quality standards, we build and test one or more release candidates before releasing the final version.
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.


To build and test a release candidate, start by cloning the canonical repository and entering its working directory:
Clone the canonical repository, and enter the clone's working directory, and check out the stabilization branch:


  git clone git@github.com:mozilla/addon-sdk.git
  git clone git@github.com:mozilla/addon-sdk.git
  cd addon-sdk
  cd addon-sdk
git checkout stabilization
Determine the version identifier for the beta or release candidate build. This should be the final release identifier (e.g. 1.2) with a suffix like "b1" or "rc2", e.g. "1.2b1":
Set JPNV (Jetpack Next Version) to the next version being built (f.e. 1.2b2):
export JPNV=1.2b1


If this is the first RC, create a branch named branch-[version] (e.g. branch-1.0b1), update references to the version in static-files/index.html and other files to the final version you are releasing (e.g. 1.0b1), then commit the change:
Tag the repository with the new version identifier:


  git checkout -b branch-1.0b1
  git tag ${JPNV}
(update the version)
git commit -a -m"update version for next release"


Otherwise, if this is the second or a subsequent RC, change to the previously-created branch:
Create a tarball and a ZIP archive:


  git checkout branch-1.0b1
  git archive --format=zip --output addon-sdk-${JPNV}.zip --prefix addon-sdk-${JPNV}/ ${JPNV}
git archive --format=tar --output addon-sdk-${JPNV}.tar --prefix addon-sdk-${JPNV}/ ${JPNV}
gzip addon-sdk-${JPNV}.tar # makes addon-sdk-${JPNV}.tar.gz


Create tarball and ZIP archives whose names include a release candidate identifier but whose directory prefixes (i.e. the directory that will be created when the archives are expanded) do not include a release candidate identifier:
{{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.}}


git archive --format=zip --output ~/addon-sdk-1.0b1rc1.zip --worktree-attributes --prefix addon-sdk-1.0b1/ HEAD
Copy the tarball/ZIP archive to the distribution server:
git archive --format=tar --output ~/addon-sdk-1.0b1rc1.tar --worktree-attributes --prefix addon-sdk-1.0b1/ HEAD
gzip ~/addon-sdk-1.0b1rc1.tar # makes addon-sdk-1.0b1rc1.tar.gz


Verify that the builds are ready for distribution by running integration and other checks on them.
scp addon-sdk-${JPNV}.tar.gz addon-sdk-${JPNV}.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/


Tag the repository with the release candidate version:
{{note|make sure the two files have the correct permissions before proceeding.}}


git tag 1.0b1rc1 branch-1.0b1
Verify that the tarball/ZIP archive is ready for distribution by running integration checks on it:


Push the branch and tag back to the canonical repository:
mkdir TEST_ZIP && cd TEST_ZIP && python ../bin/integration-scripts/integration-check --url https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-${JPNV}.zip
cd ..
mkdir TEST_TGZ && cd TEST_TGZ && python ../bin/integration-scripts/integration-check --url https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-${JPNV}.tar.gz
cd ..


git push origin --tags branch-1.0b1
{{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 archives to the staging server:
Push the stabilization branch and the tag to the canonical repository:


  scp addon-sdk-1.0b1rc1.tar.gz addon-sdk-1.0b1rc1.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/
  git push origin stabilization ${JPNV}


The packages should immediately become available on the distribution server:
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 [https://preview.addons.mozilla.org/ 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.)


https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1rc1.tar.gz
File a bug in the Builder component to get the test build uploaded to the -dev server.
https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1rc1.zip


Notify QA, the forum, and other testers about the candidate. Have them run automated & manual tests (including submitting generated XPIs to the [https://preview.addons.mozilla.org/ AMO test server]) and report any bugs they discover.
== Stabilize Codebase ==


Triage reported bugs at least daily, determine which are blockers, and get Jetpack developers to fix those blockers. If any blockers are found during an RC test cycle, spin another RC after those blockers are fixed and get testers to verify the fixes and make sure they didn't cause regressions.
Land stabilizing changes on the master branch.


An additional criteria for build quality is approval of the documentation. The documentation lead, or a Jetpack driver, must sign off on the documentation for a given release candidate to be approved for final release.
{{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.}}


== Create Marketing/PR/Evangelism Materials ==
Periodically generate a list of changes between the master and stabilization branches:


=== Update Website ===
git rev-list --right-only --cherry-pick --no-merges --pretty --reverse stabilization...master


The [https://jetpack.mozillalabs.com/ Jetpack website] lives at jetpack.mozillalabs.com. Much of its content is release-neutral. For example, links to SDK documentation point to a "latest" redirect that takes you to the latest release version of the docs. And buttons/links to download the SDK packages point to "latest" symlinks that link to the latest release packages.
{{Note|'''<tt>--right-only</tt> shows only commits on master (on the right in the symmetric diff notation <tt>stabilization...master</tt>) that are not on stabilization; <tt>--cherry-pick</tt> omits equivalent commits; <tt>--no-merges</tt> excludes merge commits (it's usually better to cherry-pick only non-merge commits); <tt>--pretty</tt> shows useful info about each commit; and <tt>--reverse</tt> shows commits chronologically from older to newer (the same order in which you are most likely to cherry-pick them successfully).}}


Some content, however, might need updating. For example, the description of the SDK on the home page might change over time as the SDK acquires additional APIs and other functionality.
Identify stabilizing changes landed on the master branch, and cherry-pick them to the stabilization branch:


To update the website, clone its code from the [https://hg.mozilla.org/labs/jetpack/ old Jetpack Prototype repository] (the code lives in the [https://hg.mozilla.org/labs/jetpack/file/tip/website website subdirectory]), change the code as needed, test your changes by loading your local working copy of the code in your browser, commit your changes, tag the changeset with the "website-production" tag (you'll need to specify <tt>-f</tt> to force Mercurial to update the existing tag), and push your changes back to the central repository.
git cherry-pick -x (REVISION ID)


=== Draft Blog Post ===
== Draft Release Announcement ==


Draft a blog post for the [http://blog.mozilla.com/addons/ Add-ons Blog] to announce the release.
Draft a release announcement blog post for the [http://blog.mozilla.com/addons/ Add-ons Blog].


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 '''&lt;!-- more -->''' element to reduce the initial size of the post, and put the post into the '''developers''', '''jetpack''', '''general''', and '''releases''' categories.
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 '''&lt;!-- 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.
After drafting the post, share it with other folks who can help edit it, such as the project's marketing manager.
Line 149: Line 172:
{{note|don't publish the post in this step. That should happen in the Release step.}}
{{note|don't publish the post in this step. That should happen in the Release step.}}


=== Write Release Notes ===
== 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.
 
Reference the release notes from the [[Jetpack/Release_Notes|List of Release Notes]].


Release notes live on the wiki at /Labs/Jetpack/SDK/Release_Notes/[VERSION] (e.g. /Labs/Jetpack/SDK/Release_Notes/0.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.
== Choose Candidate ==


= Thaw Development =
Decide to ship a candidate as the final release.


Clone the canonical repository and enter its working directory:
== Push Docs ==
 
After you have decided to ship a candidate as the final release, generate the docs for the release.
 
Clone the canonical repository, and enter the clone's working directory, check out the candidate tag, and activate the SDK:


  git clone git@github.com:mozilla/addon-sdk.git
  git clone git@github.com:mozilla/addon-sdk.git
  cd addon-sdk
  cd addon-sdk
git checkout (CANDIDATE VERSION)
source bin/activate


Update references to the version in static-files/index.html and other files to the development cycle version, which is the conservative anticipated next release followed by the "pre" suffix (e.g. 1.0b2pre), then commit and push the change:
Generate and expand the docs:


  (update references to the version)
  cfx sdocs --baseurl="https://addons.mozilla.org/en-US/developers/docs/sdk/(FINAL VERSION)/"
  git commit -a -m"update version for next development cycle"
  tar xzf addon-sdk-docs.tgz
git push origin master


Notify Jetpack code contributors that development has been thawed via a post to the forum. The post should specify that the repository is open for general checkins and that checkins no longer need driver approval.
Clone the docs repository and delete everything it contains (wbamberg: this is evidently a bit mad, but it makes no sense to me to pretend that this is a new revision, since it's generated):


{{note|in theory, you can thaw development any time after the first release candidate, since it's possible to fix release blockers on the branch. In practice, it's better to keep the tree frozen longer to focus the team's attention on release blockers.}}
git clone git@github.com:mozilla/addon-sdk-sdocs.git
cd addon-sdk-sdocs
rm -rf *
git rm *
 
Copy the docs to the docs repository, commit the changes, tag the revision as (CANDIDATE VERSION)-amo (f.e. 1.2rc1-amo), and push the changes to the docs repository:
 
cp -r ../doc/* .
git add *
git commit -m "add (CANDIDATE VERSION) docset"
git tag -a (CANDIDATE VERSION)-amo -m "tagged (CANDIDATE VERSION) docset"
git push --tags origin master
 
Ask IT to push the docs to production and update the "latest" redirect to point to the new docs via this [https://bugzilla.mozilla.org/enter_bug.cgi?bug_severity=normal&cc=wbamberg%40mozilla.com&comment=Please%20update%20the%20documentation%20for%20the%20Add-on%20SDK%20in%20conjunction%20with%20its%20X.X%20release.%0D%0A%0D%0AClone%20the%20docs%20from%20%3Cgit%3A%2F%2Fgithub.com%2Fmozilla%2Faddon-sdk-sdocs.git%3E%2C%20and%20check%20out%20the%20TAG%20tag%2C%20i.e.%3A%0D%0A%0D%0A%20%20git%20clone%20git%3A%2F%2Fgithub.com%2Fmozilla%2Faddon-sdk-sdocs.git%0D%0A%20%20cd%20addon-sdk-sdocs%0D%0A%20%20git%20checkout%20TAG%0D%0A%0D%0AThen%20push%20the%20docs%20to%20%3Chttps%3A%2F%2Faddons.mozilla.org%2Fen-US%2Fdevelopers%2Fdocs%2Fsdk%2FX.X%2F%3E.%0D%0A%0D%0ADo%20this%20at%20your%20earliest%20convenience.%20%20Then%2C%20on%20Tuesday%2C%20MONTH%20DAY%2C%20update%20the%20redirect%20at%20%3Chttps%3A%2F%2Faddons.mozilla.org%2Fen-US%2Fdevelopers%2Fdocs%2Fsdk%2Flatest%2F%3E%20to%20point%20to%20%3Chttps%3A%2F%2Faddons.mozilla.org%2Fen-US%2Fdevelopers%2Fdocs%2Fsdk%2FX.X%2F%3E.%0D%0A&component=Server%20Operations%3A%20Web%20Operations&op_sys=All&product=mozilla.org&rep_platform=All&short_desc=%5BAMO%5D%20update%20SDK%20docs%20for%20X.X%20release docs push bug template].
 
{{note|IT pushes the docs at their earliest convenience, so we can test them, but they update the ''latest'' docs redirect on the day of the release.}}
 
(Myk: should there be separate bugs for the Push Docs and Update Latest Docs Redirect steps?)


= Release =
= Release =


== Bless Candidate ==
== Create Final Build ==
 
Create a final tarball/ZIP archive, from the same sources as the most recent
release candidate (JPRCV). This uses the same steps as "Spin Test Builds"
above, but with a finalized version name:
 
git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk
git checkout stabilization
 
Recall the version of the last release candidate:
 
export JPRCV=1.2rc2
 
Determine the version identifier for the final release (e.g. 1.2), and store
it in JPFV:
 
export JPFV=1.2
 
Tag the repository with the final version identifier, but do not push the tag
until all subsequent validation steps have been completed:
 
git tag ${JPFV}
 
Confirm that the revision id for the final release is the same as the last
release candidate:
 
git diff ${JPRCV} ${JPFV}
# should produce no output
 
Create a tarball and ZIP archive:
 
git archive --format=zip --output addon-sdk-${JPFV}.zip --prefix addon-sdk-${JPFV}/ ${JPFV}
git archive --format=tar --output addon-sdk-${JPFV}.tar --prefix addon-sdk-${JPFV}/ ${JPFV}
gzip addon-sdk-${JPFV}.tar # makes addon-sdk-${JPFV}.tar.gz
 
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:
 
scp stage.mozilla.org:/pub/mozilla.org/labs/jetpack/addon-sdk-${JPRCV}.tar.gz ./
tar xf addon-sdk-${JPRCV}.tar.gz
tar xf addon-sdk-${JPFV}.tar.gz
diff -urN addon-sdk-${JPRCV} addon-sdk-${JPFV}
# should show one line different in python-lib/cuddlefish/_version.py
# git_refnames= should change from (JPRCV,..) to (JPRCV,JPFV,..). e.g.:
#  git_refnames = " (HEAD, 1.4rc4, origin/stabilization, stabilization)"
#    changes to
#  git_refnames = " (HEAD, 1.4rc4, 1.4, origin/stabilization, stabilization)"
 
In the newly generated and unpacked tarball, confirm that the code reports
the correct version (and *not* the rcN version):
 
addon-sdk-${JPFV}/bin/cfx --version
# Add-on SDK $JPFV (hex revision id)
 
Everything looks good.
 
== Commit (to the) New Release ==
 
Now copy the archives to the distribution server:
 
scp addon-sdk-${JPFV}.tar.gz addon-sdk-${JPFV}.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/
{{note| make sure file permissions are correct (644) on both files!}}
 
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 ==


Copy the archives for the latest release candidate to files without the release candidate identifier in the name:
Requirements: working checkout of AMO-validator & prerequisites. Please see the [https://github.com/mozilla/amo-validator/blob/master/README.rst AMO Validator Readme] for the gory details. We should fork the amo-validator repo and then for each release do the following:


ssh stage.mozilla.org
Step 1: update the hash file in our forked repo:
cd /pub/mozilla.org/labs/jetpack/
<pre>
cp addon-sdk-1.0b1rc1.tar.gz addon-sdk-1.0b1.tar.gz
git pull mozamo master # update from the upstream 'mozamo' repo
cp addon-sdk-1.0b1rc1.zip addon-sdk-1.0b1.zip
cd jetpack
./generate_jp_whitelist.sh
cd ../
</pre>
Make extra-super sure the pickle file can be git add'ed. If it doesn't show up:
<pre>
rm validator/testcases/jetpack_data.txt.pickle
nosetests</pre>
Then go ahead:
<pre>
git add validator/testcases/jetpack_data.txt
git add validator/testcases/jetpack_data.txt.pickle
git commit -m "Updated amo-validator with hashes for SDK version x.x.x"
git push origin master</pre>


Update the /pub/mozilla.org/labs/jetpack/.htaccess file to redirect the "latest" symlinks to the new release:
Step 2: We issue a pull request to the mozilla/amo-validator and <del>pester</del> 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!!!'''


Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.zip
Step 3: We do some testing on AMO's existing test infrastructure on allizom.com. The test should be essentially:
Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.tar.gz
* run the validator on xpi files that use the new version
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.zip
* ensure the validator does not raise errors on SDK core files.
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.tar.gz


Test the latest symlinks to ensure they correctly provide the new release.
Step 4: The changes are pushed with the regular Thursday AMO push.


== Update Website ==
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.


In the bug you filed earlier about pushing the website changes to production, comment that now is the time to do the work and wait for its assignee to do it.
== File Builder bug to push build ==


== Publish Blog Post ==
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 [https://bugzilla.mozilla.org/enter_bug.cgi?product=addons.mozilla.org|against 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:
git submodule add git://github.com/mozilla/addon-sdk.git lib/addon-sdk-(VERSION)
cd lib/addon-sdk-(VERSION)
git checkout (VERSION)
cd ../..
git add lib/addon-sdk-(VERSION)
#Don't forget to update LOWEST_APPROVED_SDK and TEST_SDK in settings.py for the new SDK version!
git add settings.py
* 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:
 
Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).zip
Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).tar.gz
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).zip
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).tar.gz
 
Test the symlinks to ensure they correctly provide the new release.
 
== Update Latest Docs Redirect ==
 
Update the latest docs redirect to point to the new version's docs.
 
== Publish Release Announcement ==


Access the Add-ons blog's Wordpress admin page and go to Posts. Publish the post you previously drafted.
Access the Add-ons blog's Wordpress admin page and go to Posts. Publish the post you previously drafted.


{{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.}}
{{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:
 
https://github.com/mozilla/addon-sdk/tree/(FINAL VERSION)
 
Update the IRC topic on #jetpack to announce the new release.
 
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!


== Notify Forum ==
Physically or virtually high-five or fist-jab contributors.


Notify the discussion forum about the release.
= Review =


= Feel Good =
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.


For minor releases (every month):
= Panic =


* physically high-five or fist jab local Jetpack contributors;
Hot-Fixes are releases that are made directly on the "release" branch, rather
* virtually high-five or fist jab remote Jetpack contributors.
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).


For major milestones (every 6-9 months):
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.


* do everything you do for minor releases;
The basic idea is that the "release" branch should always be a descendant of
* celebrate over dinner/drinks with local Jetpack contributors;
the "stabilization" branch, so that normal releases (made on stabilization)
* celebrate over the internet with remote Jetpack contributors.
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.


= Review the Process =
The general process is:


After every release, it's useful to review the process described here and update it as appropriate. This can take the form of a formal post mortem, solicitation of feedback in the regular weekly meeting, or individual review by folks who were involved in the release.
* 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


= Checklist Template =
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:


The checklist table below can be used for tracking the status of each step in the process, per release.
* 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


=Jetpack Release Checklist=


{| class="fullwidth-table"
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.
|- style="background:#efefef"
| '''Step'''
| '''Status'''
| '''Owner'''
|-
| Freeze Development
|
|
|-
| Update Credits
|
|
|-
| Prepare to Release
|
|
|-
| &nbsp;&nbsp; Notify Relevant Parties &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Notify Forum &nbsp;&nbsp;&nbsp;&nbsp;
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Notify Ambassadors &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Notify PR &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Notify Product Delivery Team &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Notify IT &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp; Build/Test Release Candidate(s) &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp; Create Marketing/PR/Evangelism Materials &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Update Website &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Write Blog Post &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp;&nbsp;&nbsp; Write Release Notes &nbsp;&nbsp;&nbsp;&nbsp;
|
|
|-
| Thaw Development
|
|
|-
| Release
|
|
|-
| &nbsp;&nbsp; Bless Candidate &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp; Update Website &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp; Publish Blog Post &nbsp;&nbsp;
|
|
|-
| &nbsp;&nbsp; Notify Forum &nbsp;&nbsp;
|
|
|-
| Feel Good
|
|
|-
| Review the Process
|
|
|}

Latest revision as of 09:19, 20 March 2013

This document describes the process by which versions of the Add-on SDK are released. For information about the process by which versions of the SDK are developed, see Jetpack/Development Process.

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.

<createbox> align=left type=create preload=Jetpack/SDK/TEMPLATE/Release_Checklist default=1.xx prefix=Jetpack/SDK/Release_Checklist/ </createbox>

The template for this form is here.

Past SDK Release checklists

Merge Master to Stabilization

Clone the canonical repository, and enter the clone's working directory:

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

Merge the master (development) branch to the stabilization branch:

git checkout stabilization
git merge --no-commit master
# resolve conflicts, if any (don't resolve install.rdf yet!)
git commit -m "merge master into stabilization to start the N.N release cycle"

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

Change the Firefox minVersion/maxVersion compatibility identifiers on the stabilization branch per the Jetpack/Development Process.

Commit the changes:

git commit -a -m"update Firefox minVersion/maxVersion to anticipated current/next versions of Firefox"

Change back to the master branch:

git checkout master

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:

git push origin master stabilization
git push --tags origin

File Tracking Bug

File a bug to track the release using this release tracking bug template.

Notify Relevant Parties

Community

Notify project participants in the discussion forum. Mention the tentative release date, and reference the tracking bug and release checklist.

Product Planning

Notify product planners via their weekly meeting.

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:

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

Determine the version identifier for the beta or release candidate build. This should be the final release identifier (e.g. 1.2) with a suffix like "b1" or "rc2", e.g. "1.2b1":

Set JPNV (Jetpack Next Version) to the next version being built (f.e. 1.2b2):

export JPNV=1.2b1

Tag the repository with the new version identifier:

git tag ${JPNV}

Create a tarball and a ZIP archive:

git archive --format=zip --output addon-sdk-${JPNV}.zip --prefix addon-sdk-${JPNV}/ ${JPNV}
git archive --format=tar --output addon-sdk-${JPNV}.tar --prefix addon-sdk-${JPNV}/ ${JPNV}
gzip addon-sdk-${JPNV}.tar # makes addon-sdk-${JPNV}.tar.gz
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.

Copy the tarball/ZIP archive to the distribution server:

scp addon-sdk-${JPNV}.tar.gz addon-sdk-${JPNV}.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/
Note: make sure the two files have the correct permissions before proceeding.

Verify that the tarball/ZIP archive is ready for distribution by running integration checks on it:

mkdir TEST_ZIP && cd TEST_ZIP && python ../bin/integration-scripts/integration-check --url https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-${JPNV}.zip
cd ..
mkdir TEST_TGZ && cd TEST_TGZ && python ../bin/integration-scripts/integration-check --url https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-${JPNV}.tar.gz
cd ..
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:

git rev-list --right-only --cherry-pick --no-merges --pretty --reverse stabilization...master
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

Draft a release announcement blog post for the Add-ons Blog.

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.

Reference the release notes from the List of Release Notes.

Choose Candidate

Decide to ship a candidate as the final release.

Push Docs

After you have decided to ship a candidate as the final release, generate the docs for the release.

Clone the canonical repository, and enter the clone's working directory, check out the candidate tag, and activate the SDK:

git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk
git checkout (CANDIDATE VERSION)
source bin/activate

Generate and expand the docs:

cfx sdocs --baseurl="https://addons.mozilla.org/en-US/developers/docs/sdk/(FINAL VERSION)/"
tar xzf addon-sdk-docs.tgz

Clone the docs repository and delete everything it contains (wbamberg: this is evidently a bit mad, but it makes no sense to me to pretend that this is a new revision, since it's generated):

git clone git@github.com:mozilla/addon-sdk-sdocs.git
cd addon-sdk-sdocs
rm -rf *
git rm *

Copy the docs to the docs repository, commit the changes, tag the revision as (CANDIDATE VERSION)-amo (f.e. 1.2rc1-amo), and push the changes to the docs repository:

cp -r ../doc/* .
git add *
git commit -m "add (CANDIDATE VERSION) docset"
git tag -a (CANDIDATE VERSION)-amo -m "tagged (CANDIDATE VERSION) docset"
git push --tags origin master

Ask IT to push the docs to production and update the "latest" redirect to point to the new docs via this docs push bug template.

Note: IT pushes the docs at their earliest convenience, so we can test them, but they update the latest docs redirect on the day of the release.

(Myk: should there be separate bugs for the Push Docs and Update Latest Docs Redirect steps?)

Release

Create Final Build

Create a final tarball/ZIP archive, from the same sources as the most recent release candidate (JPRCV). This uses the same steps as "Spin Test Builds" above, but with a finalized version name:

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

Recall the version of the last release candidate:

export JPRCV=1.2rc2

Determine the version identifier for the final release (e.g. 1.2), and store it in JPFV:

export JPFV=1.2

Tag the repository with the final version identifier, but do not push the tag until all subsequent validation steps have been completed:

git tag ${JPFV}

Confirm that the revision id for the final release is the same as the last release candidate:

git diff ${JPRCV} ${JPFV}
# should produce no output

Create a tarball and ZIP archive:

git archive --format=zip --output addon-sdk-${JPFV}.zip --prefix addon-sdk-${JPFV}/ ${JPFV}
git archive --format=tar --output addon-sdk-${JPFV}.tar --prefix addon-sdk-${JPFV}/ ${JPFV}
gzip addon-sdk-${JPFV}.tar # makes addon-sdk-${JPFV}.tar.gz

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:

scp stage.mozilla.org:/pub/mozilla.org/labs/jetpack/addon-sdk-${JPRCV}.tar.gz ./
tar xf addon-sdk-${JPRCV}.tar.gz
tar xf addon-sdk-${JPFV}.tar.gz
diff -urN addon-sdk-${JPRCV} addon-sdk-${JPFV}
# should show one line different in python-lib/cuddlefish/_version.py
# git_refnames= should change from (JPRCV,..) to (JPRCV,JPFV,..). e.g.:
#   git_refnames = " (HEAD, 1.4rc4, origin/stabilization, stabilization)"
#     changes to
#   git_refnames = " (HEAD, 1.4rc4, 1.4, origin/stabilization, stabilization)"

In the newly generated and unpacked tarball, confirm that the code reports the correct version (and *not* the rcN version):

addon-sdk-${JPFV}/bin/cfx --version
# Add-on SDK $JPFV (hex revision id)

Everything looks good.

Commit (to the) New Release

Now copy the archives to the distribution server:

scp addon-sdk-${JPFV}.tar.gz addon-sdk-${JPFV}.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/
Note: make sure file permissions are correct (644) on both files!

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 1: update the hash file in our forked repo:

git pull mozamo master # update from the upstream 'mozamo' repo
cd jetpack
./generate_jp_whitelist.sh
cd ../

Make extra-super sure the pickle file can be git add'ed. If it doesn't show up:

rm validator/testcases/jetpack_data.txt.pickle
nosetests

Then go ahead:

git add validator/testcases/jetpack_data.txt
git add validator/testcases/jetpack_data.txt.pickle
git commit -m "Updated amo-validator with hashes for SDK version x.x.x"
git push origin master

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:
git submodule add git://github.com/mozilla/addon-sdk.git lib/addon-sdk-(VERSION)
cd lib/addon-sdk-(VERSION)
git checkout (VERSION)
cd ../..
git add lib/addon-sdk-(VERSION)
#Don't forget to update LOWEST_APPROVED_SDK and TEST_SDK in settings.py for the new SDK version!
git add settings.py
  • 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:

Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).zip
Redirect 307 /pub/mozilla.org/labs/jetpack/addon-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).tar.gz
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.zip https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).zip
Redirect 307 /pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-(FINAL VERSION).tar.gz

Test the symlinks to ensure they correctly provide the new release.

Update Latest Docs Redirect

Update the latest docs redirect to point to the new version's docs.

Publish Release Announcement

Access the Add-ons blog's Wordpress admin page and go to Posts. Publish the post you previously drafted.

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:

https://github.com/mozilla/addon-sdk/tree/(FINAL VERSION)

Update the IRC topic on #jetpack to announce the new release.

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.