MozillaWiki

Jetpack/Release Process: Difference between revisions

< Jetpack
No edit summary
 
(108 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}}


= Update Credits Page =
== Merge Master to Stabilization ==


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.
Clone the canonical repository, and enter the clone's working directory:


= Prepare to Release =
git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk


Preparing to release involves doing three different sets of things, which can be done in parallel:
Merge the master (development) branch to the stabilization branch:


* file tracking bugs
git checkout stabilization
* notify relevant parties
git merge --no-commit master
* build/test release candidate(s)
# resolve conflicts, if any (don't resolve install.rdf yet!)
* create marketing/PR/evangelism materials
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:


File a bug to track code blockers of the release and another to track the overall release.
git diff master stabilization
# only differences should be in install.rdf, minVersion/maxVersion


* [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%20Jetpack%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.&component=Jetpack%20SDK&op_sys=All&priority=--&product=Mozilla%20Labs&rep_platform=All&short_desc=x.x%20release%20blocker%20bugs code blockers bug template]
Change the Firefox minVersion/maxVersion compatibility identifiers on the stabilization branch per the [[Jetpack/Development Process]].
* [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%20Jetpack%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.&component=Jetpack%20SDK&op_sys=All&product=Mozilla%20Labs&rep_platform=All&short_desc=release%20Jetpack%20SDK%20x.x&assigned_to=myk@mozilla.org&dependson=(code%20blockers%20bug%20number) release bug template]
 
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 [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 Relevant Parties ==
== Notify Relevant Parties ==


=== Notify Forum ===
=== Community ===


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.
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 Ambassadors ===
=== Product Planning ===


Notify Jetpack ambassadors about the release. Include the same information in the notice sent to the discussion forum.
Notify product planners via their [[Firefox/Planning|weekly meeting]].


=== Notify PR ===
=== PR ===


Contact the Mozilla PR team and let them know about the release by emailing press@mozilla.com. 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).
Notify the Mozilla PR team (communications@mozilla.com).


Notify them again if anything changes (f.e. the release date).
PR likes to have the email, despite sitting in the planning meetings.


=== Notify Product Delivery Team ===
== Spin Test Builds ==


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 if asked to do so.
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.


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


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.
git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk
git checkout stabilization


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%20Jetpack%20SDK%20source%20tree%20in%20preparation%20for%20the%20release%20of%20Jetpack%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%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%20Jetpack%20SDK%20x.x%20website%20changes%20to%20production IT request bug template]), cc:ing ":zandr", to have the website changes pushed to production, including:
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":


# pushing the new version's docs to the website;
Set JPNV (Jetpack Next Version) to the next version being built (f.e. 1.2b2):
# 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.
export JPNV=1.2b1


== Build/Test Release Candidate(s) ==
Tag the repository with the new version identifier:


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.
git tag ${JPNV}


To build and test a release candidate, start by cloning the repository and entering its working directory:
Create a tarball and a ZIP archive:


  hg clone ssh://hg.mozilla.org/labs/jetpack-sdk/ jetpack-sdk
  git archive --format=zip --output addon-sdk-${JPNV}.zip --prefix addon-sdk-${JPNV}/ ${JPNV}
  cd jetpack-sdk
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


If this is the first RC, update references to the version in static-files/index.html and other files to the final version (e.g. 0.3), then commit the change:
{{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.}}


hg commit -m"update version for next release"
Copy the tarball/ZIP archive to the distribution server:


Tag the repository with both the release candidate version and the final version (e.g. 0.3rc1 and 0.3):
scp addon-sdk-${JPNV}.tar.gz addon-sdk-${JPNV}.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/


hg tag 0.3rc1
{{note|make sure the two files have the correct permissions before proceeding.}}
hg tag 0.3


{{note|you tag the repository with the final version in addition to the release candidate version because the code you are tagging is potentially both the code you ship in the RC and the code you ship in the final release, if you find no problems with it that require spinning another RC. You also do it because then you can bundle the code into a directory named after the final release using Mercurial's built-in tag-based archiving feature, as described below.}}
Verify that the tarball/ZIP archive is ready for distribution by running integration checks on it:


{{note|if this is a second or subsequent release candidate, you have to specify the <tt>--force</tt> flag to <tt>hg tag</tt> for the final version (i.e. <tt>hg tag --force 0.3</tt> in order to update the existing tag.}}
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 ..


Push the changes to the central repository:
{{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.}}


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


The central repository will automatically build tarball and ZIP archives based on the version tags you created. Download the packages for the '''final version tag''':
git push origin stabilization ${JPNV}


https://hg.mozilla.org/labs/jetpack-sdk/archive/0.3.tar.gz
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://hg.mozilla.org/labs/jetpack-sdk/archive/0.3.zip


The packages you download will have "jetpack-sdk-" prepended to them, e.g. jetpack-sdk-0.3.tar.gz and jetpack-sdk-0.3.zip. Rename the files to reflect the release candidate version:
File a bug in the Builder component to get the test build uploaded to the -dev server.


mv jetpack-sdk-0.3.tar.gz jetpack-sdk-0.3rc1.tar.gz
== Stabilize Codebase ==
mv jetpack-sdk-0.3.zip jetpack-sdk-0.3rc1.zip


Push the packages to the staging server:
Land stabilizing changes on the master branch.


scp jetpack-sdk-0.3rc1.tar.gz jetpack-sdk-0.3rc1.zip stage.mozilla.org:/pub/mozilla.org/labs/jetpack/
{{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.}}


The packages should immediately become available on the distribution server:
Periodically generate a list of changes between the master and stabilization branches:


  https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-0.3rc1.tar.gz
  git rev-list --right-only --cherry-pick --no-merges --pretty --reverse stabilization...master
https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-0.3rc1.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.
{{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).}}


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.
Identify stabilizing changes landed on the master branch, and cherry-pick them to the stabilization 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.
git cherry-pick -x (REVISION ID)


== Create Marketing/PR/Evangelism Materials ==
== Draft Release Announcement ==


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


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.
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.


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.
After drafting the post, share it with other folks who can help edit it, such as the project's marketing manager.


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.
{{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 [[Jetpack/Release_Notes|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.


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


The [http://mozillalabs.com/jetpack/ Jetpack blog] lives at mozillalabs.com/jetpack. Each release should be accompanied by a blog post that announces and describes the release.
git clone git@github.com:mozilla/addon-sdk.git
cd addon-sdk
git checkout (CANDIDATE VERSION)
source bin/activate


To write 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 size of the post when syndicated to the general Mozilla Labs blog, and put the post into the '''Release''' category so the blog can style it appropriately.
Generate and expand the docs:


{{note|don't publish the post in this step. That should happen in the Release step.}}
cfx sdocs --baseurl="https://addons.mozilla.org/en-US/developers/docs/sdk/(FINAL VERSION)/"
tar xzf addon-sdk-docs.tgz


=== Write Release Notes ===
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):


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.
git clone git@github.com:mozilla/addon-sdk-sdocs.git
cd addon-sdk-sdocs
rm -rf *
git rm *


= Thaw Development =
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:


Update references to the version in static-files/index.html and other files to the development cycle version (e.g. 0.4pre), then commit and push the change:
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


hg commit -m"update version for next development cycle"
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].
hg push


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.
{{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.}}


{{note|in theory, you can thaw development any time after the first release candidate, since it's possible to branch the tree at that point and fix release blockers on the branch. In practice, it's better to keep the tree frozen longer, both to focus developers' attention on release blockers and to obviate the encumberance of branching. However, as the number of active Jetpack code contributors increases, and if stabilization cycles become longer, it may start to become better to thaw earlier.}}
(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 ==
 
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:
 
Step 1: update the hash file in our forked repo:
<pre>
git pull mozamo master # update from the upstream 'mozamo' repo
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>
 
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!!!'''
 
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 [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 ==


Blessing the last release candidate simply entails copying its archives to files with names reflecting the final release and updating the "latest" symlinks to point to those new files:
Update the latest docs redirect to point to the new version's docs.


ssh stage.mozilla.org
== Publish Release Announcement ==
cd /pub/mozilla.org/labs/jetpack/
cp jetpack-sdk-0.3rc1.tar.gz jetpack-sdk-0.3.tar.gz
cp jetpack-sdk-0.3rc1.zip jetpack-sdk-0.3.zip
rm jetpack-sdk-latest.tar.gz; ln -s jetpack-sdk-0.3.tar.gz jetpack-sdk-latest.tar.gz
rm jetpack-sdk-latest.zip; ln -s jetpack-sdk-0.3.zip jetpack-sdk-latest.zip


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


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.
{{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.}}


== Update Blog ==
== Notify Community ==


The [http://mozillalabs.com/jetpack/ Jetpack blog] lives at mozillalabs.com/jetpack. Its content (by which I mean the content that surrounds the blog posts, i.e. logos, navigation links, etc.) is release-neutral, so it generally doesn't need changing.
Notify the discussion forum about the release. Include a link to the release tag:


If that ever changes, then it will need to be updated. Since there is no way to stage changes to the blog, this will here in the Release step rather than in the Prepare to Release step.
https://github.com/mozilla/addon-sdk/tree/(FINAL VERSION)


{{note|changes to the blog can take several hours to show up on the site because of server-side caching. To check that your changes have been applied, add "?[some unique string]" to the end of the URL, which bypasses the cache.}}
Update the IRC topic on #jetpack to announce the new release.


== Publish Blog Post ==
File a bug in the Builder component to get the new release pushed to the production Builder server.


Access the blog's Wordpress admin page and go to Posts. Publish the post you previously wrote.
= Bask =


{{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.}}
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
|
|
|-
| 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;&nbsp;&nbsp; Documentation Review &nbsp;&nbsp;&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; Update Blog &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.

Retrieved from "https://wiki.mozilla.org/index.php?title=Jetpack/Release_Process&oldid=639159"