Jetpack/Development Process: Difference between revisions

← Older edit

Jetpack/Development Process (view source)

Revision as of 08:07, 19 June 2012

3,915 bytes added , 19 June 2012

___________________________

Taewong

Confirmed users

235

edits

@@ Line 1: / Line 1: @@
-= Goals =
+This document describes the process (a.k.a. "flow") by which the Add-on SDK is developed. For information about the process by which versions of the SDK are released, see [[Labs/Jetpack/Release|Release Process]].
-* ship frequently on a regular schedule
+= Release Schedule =
-* maintain compatibility with new versions of Firefox
-* minimize the number of branches and channels
-= Non-goals =
+We ship a stable SDK release on a regular schedule every six weeks, at least as often as Firefox, to ensure we can accommodate incompatible changes to Firefox and remain compatible with it. Each release undergoes six weeks of development and six of stabilization, so a complete development cycle lasts twelve weeks, and cycles overlap by six weeks (while one release is stabilized, the next one is developed).
-* coordinate dependencies between products such that
+We release each SDK version three weeks before each new version of Firefox is released. This allows enough time for compatibility fixes to land on the SDK's stabilization branch after Firefox stops accepting incompatible changes (at the time it merges from aurora to beta?) while still giving AMO and addon developers enough time to update addons to use the new version of the SDK.
-** the SDK ships APIs for new Firefox features before the features ship in Firefox
-** Firefox ships support for new SDK features at the same time the features ship in the SDK
-= Process =
+{{note|SDK 1.0's schedule did not follow this process. SDK 1.1's schedule was slightly irregular. SDK 1.2's stabilization cycle and SDK 1.3's development cycle were only five weeks long in order to change the offset between SDK and Firefox releases from two weeks to three weeks.}}
-We ship a stable SDK release on a regular schedule every six weeks. Each release undergoes six weeks of development and six of stabilization, so a complete cycle lasts twelve weeks, and release cycles overlap by six weeks (while one release is stabilized, the next one is developed).
+{{note|Further readings about the Firefox development and release process can be found here: [http://mozilla.github.com/process-releases/draft/development_overview/ overview], [http://mozilla.github.com/process-releases/draft/development_specifics/ specifics].}}
-We commit code to three branches: a development branch (dev), a stabilization branch (stab), and a release branch (rel). Each release spends six weeks on each branch, starting with six weeks of open development on dev, after which it is merged to stab; continuing with six weeks of restricted stabilization on stab, after which it is merged to rel; and concluding with six weeks of statis on rel.
+The [[Jetpack/SDK_2012_Release_Schedule | Add-on SDK 2012 Release Schedule]] shows the SDK releases we expect to see in 2012, and shows the range of compatible Firefox versions in a tooltip.
-We distribute code to three distribution channels: an unstable development channel (dev), a semi-stable test channel (test), and a stable release channel (rel). The dev channel is the code repository itself; we don't produce dev builds. The test channel is the project discussion group; we produce alpha, beta, release candidate (candidate), and final release (final) builds at least once per week and announce them in the group. The rel channel is the Add-ons Blog (and other communications, as appropriate); we announce final builds in the blog.
+Note that this range is not fixed for a given SDK version, but changes as an SDK goes through Development and Beta states, and as the set of available Firefox versions changes, according to the [[#SDK_Releases_and_Firefox_Compatibility | algorithm described below]].
-We don't provide automated updates to newer releases, but we may do so in the future.
+<h2>SDK Releases and Firefox Compatibility</h2>
+Each SDK is compatible with a particular range of Firefox versions: meaning that it's tested against those versions, and add-ons it produces will be marked as compatible with those versions.
+<h3>Firefox Versions</h3>
+At any time, there are four Firefox versions that matter:
+* Release
+* Beta (release+1)
+* Aurora (beta+1)
+* Development version on moz-central (aurora+1)
+Every 6 weeks, a new Firefox is released, and everyone moves along:
+<pre>
+Release     ->  X
+Beta        ->  Release
+Aurora      ->  Beta
+Development ->  Aurora
+            ->  Development
+</pre>
+The [[RapidRelease/Calendar|Rapid Release Calendar]] shows what this looks like for the second half of 2011 and the first half of 2012.
+<h3>SDK Versions</h3>
+The SDK release process mirrors that for Firefox, except that the SDK does not have separate Aurora and Beta states. So with the SDK we have three interesting versions at any given time:
+* Release
+* Beta (or Stabilization)(release+1)
+* Development version on [https://github.com/mozilla/addon-sdk GitHub] (beta+1)
+As for Firefox, every 6 weeks a new SDK is released, and everyone moves along.
+<pre>
+Release     ->  X
+Beta        ->  Release
+Development ->  Beta
+            ->  Development
+</pre>
+'''SDK Development Version'''
+An SDK in the Development state is compatible with all four of the current Firefox versions.  Each time a new version of Firefox is released, the SDK drops compatibility with the previous release of Firefox.
+'''SDK Released Version'''
+An SDK in the Release state is compatible with the Release Firefox and the Beta Firefox at the time of the SDK's release.
-Feature development happens on the development branch. It is subject to quality controls (reviews, unit tests, etc.). We may introduce additional quality controls in the near future (f.e. a requirement that new features and enhancements initially be marked experimental and be isolated from non-experimental use of the product).
+So: 1.4 ships on January 10th 2012. At that time, the released Firefox will be 9, and the Beta will be 10. Therefore 1.4 will support Firefoxes 9 and 10.
-Feature stabilization takes place on the stabilization branch. We merge to stab right after we ship the final build for the previous release. The stabilization period lasts six weeks and comprises three two week periods: alpha, beta, and candidate. During the alpha period, we address beta blockers, raising quality to the beta level. During the beta period, we address release blockers, raising quality to the release level. During the candidate period, we bake and prepare the release.
+'''SDK Beta/Stabilization Version'''
+An SDK in the Stabilization state is compatible with the same Firefox versions as it will be compatible with in Release, ''plus any earlier versions still in existence''.
-We achieve quality goals by fixing bugs and cutting features.
+So as long as Firefox 8 is still the current Release, and Firefox 9 is the Beta, and 10 is Aurora, then SDK 1.4 in Stabilization supports 8, 9, 10. Once Firefox 9 is released, halfway through the stabilization of SDK 1.4, Stabilization drops support for Firefox 8.
-Releases have versions of the format major.minor[.fix], and we communicate them to users. We typically increment the minor number for each release. We add a "fix" number and ship a release with it only under exceptional circumstances (f.e. an urgent security issue).
+= Branches =
-The branches look something like this:
+We maintain three branches: a development branch (dev), a stabilization branch (stab), and a release branch (rel). Each release spends six weeks on each branch, starting with six weeks of feature development on dev, after which it is merged to stab; continuing with six weeks of feature stabilization on stab, after which it is merged to rel; and concluding with six weeks of stasis on rel.
 [[Image:Addon-sdk-branches.png]]
-SDK releases precede the Firefox releases they accompany by enough time for us to repackage AMO-hosted addons with the SDK release but not by too much time to prevent us from tracking and addressing compatibility issues.
+Code changes are subject to conventional Mozilla quality controls (reviews, unit tests, etc.). We may introduce additional quality controls in the future (f.e. a requirement that new features and enhancements initially be marked experimental and be isolated from non-experimental use of the product). We achieve quality goals for stab and rel by fixing bugs and cutting features.
-Stab maintains compatibility with its accompanying Firefox release (i.e. the one on Firefox's beta branch when the SDK release ships). Dev maintains compatibility with the next two Firefox releases (the ones on Firefox's aurora and central branches when dev merges to stab).
+Rel maintains compatibility with Firefox's release and beta branches. Stab maintains compatibility with Firefox's beta and aurora branches. Dev maintains compatibility with all current Firefox branches.
-The next SDK release after 1.0 is 1.1, and it accompanies Firefox 7 (skipping 6). Its schedule is slightly irregular to accommodate that target. If SDK 1.0 is found to be incompatible with Firefox 6, we address it in a 1.0.1 release branched from the 1.0 tag.
+= Distribution Channels =
-The schedule for the next few releases (and their accompanying Firefox releases) looks like this:
+We distribute code to three distribution channels: an unstable development channel, a semi-stable test channel, and a stable release channel.
-[[Image:Addon-sdk-schedule.png]]
+The development channel is the code repository itself; we encourage interested parties to clone it or download source tarballs from it. The test channel is the project discussion group; we spin beta, release candidate (candidate), and final release (final) builds once per week and announce them in the group. The release channel is the Add-ons Blog (and other communications, as appropriate); we announce final release builds in the blog.
-= When What Can Land =
+We don't provide automated updates to newer releases, but we may do so in the future.
-{{draft|}}
+= Version Identifiers =
-In general, new features and enhancements to existing features can land only on the development branch, while bug fixes can land on the development branch, the stabilization branch, or both.
+Releases have version identifiers of the format (major).(minor)[.fix], and we communicate them to users. We typically increment the minor number for each release. We add a "fix" number and ship a release with it only under exceptional circumstances (f.e. an urgent security issue).
-New docs and docs enhancements that do not involve code changes, however, can land on the stabilization branch during the first two weeks of each stabilization period (i.e. while the code is in alpha), so tech writers have time to document late-breaking changes, and because such changes are less likely to cause regressions.
+We update the version on dev at the beginning of each cycle to be (major).(minor)a0, where (major).(minor) represents the identifier with which we intend to ship the code under development, f.e. 1.3a0 when dev represents the code we intend to ship as SDK 1.3, which indicates:
+* via (major).(minor), the version under development;
+* via "a", that the code is at an alpha level of quality;
+* via "0", that the code is unreleased and precedes any test build we may spin.
+We update the version number on stab before each test build we spin from that branch. For a beta, we set it to (final)b(n), where (final) represents the release identifier of the final release build and (n) represents the ordinal position of the build in the set of betas. For both release candidates and final release builds, we set the version to (final).
 = Landing Requirements =
-{{draft|}}
+New features and enhancements to existing features can land only on dev, except that new docs and docs enhancements can land on stab during the first three weeks of each stabilization period, so tech writers have time to document late-breaking changes, and because such changes are less likely to cause regressions.
+Bug fixes can land on dev, stab, or both. Fixes for bugs that affect both dev and stab should land on dev and then get cherry-picked to stab. (In the future we may land such changes on stab and merge them to dev.)
+In order to land, a change must provide a notable benefit and not unintentionally change existing functionality (f.e. busting tests). If it changes or adds a user-facing interface, including APIs implemented as CommonJS modules and command-line tools/commands/flags, it must also pass an API/interface review by the technical lead.
-In order to land, a change must provide a notable benefit and not regress tests. In most cases, it must also pass a code review by an SDK code reviewer. And if it changes or adds a user-facing API, it must also pass an API review by the technical lead.
+The bar for changing ''supported'' functionality is very high, and landings must not do so except for very good reason and along with every reasonable effort, in documentation and otherwise, to ameliorate the impact on existing users. The bar for changing ''internal'' and ''experimental'' functionality is lower, and landings can do so as appropriate.
-Exceptions to the code review requirement include:
+In most cases, landings must also pass review by an SDK reviewer. Exceptions to the review requirement include:
-* release management changes (f.e. version number bumps)
+* release engineering changes (f.e. version number bumps)
-* additions to the [https://addons.mozilla.org/en-US/developers/docs/sdk/1.0/dev-guide/appendices/credits.html credits]
+* additions to the credits
 * obvious and trivial test bustage fixes
 * obvious and trivial typo (spelling, grammar) fixes in documentation
-= TBD =
+After landing a change, the committer must check the [https://tbpl.mozilla.org/?tree=Jetpack&usetinderbox=1 test automation dashboard] to verify the change does not cause a test regression.  Regressions must be resolved by fixing the bug causing the regression or reverting the change.
-* where stabilization fixes land (on dev, then cherry-pick to stab, or on stab, then merge to dev?)
-* whether stab is a single branch or a series of them, one per release (if stab is a single branch, it may be easier to integrate with test automation; if each release has its own stab branch, we don't have to cut another branch to take a blocker fix after we release the candidate build and merge dev to stab for the next release)
-* how many weeks to precede each Firefox release (two? three?)
-* conditions under which to increment the major number
-* how to identify, and when to increment, the version in manifests, code, and docs on the two branches
-* when to drop compatibility with older releases of Firefox
 = Rationale =
@@ Line 95: / Line 139: @@
 = References =
-* [http://thinking-in-code.blogspot.com/2010/07/train-model-of-software-development.html Train Model of Software Development]
+* [http://thinking-in-code.blogspot.com/2010/07/train-model-of-software-development.html Dean Povey: Train Model of Software Development]
-* [http://pauljulius.com/blog/2009/09/03/feature-branches-are-poor-mans-modular-architecture/ Feature Branches are Poor Man's Modular Architecture]
+* [http://pauljulius.com/blog/2009/09/03/feature-branches-are-poor-mans-modular-architecture/ Paul Julius: Feature Branches are Poor Man's Modular Architecture]
+* [http://martinfowler.com/bliki/FeatureBranch.html Martin Fowler: FeatureBranch]
+* [http://mykzilla.blogspot.com/2011/09/gitflow-vs-sdk.html Myk Melez: gitflow vs. the SDK]
+* [http://lloyd.io/applying-gitflow Lloyd Hillaiel: Applying Gitflow]
+* [http://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen: A successful Git branching model]
+* [http://scottchacon.com/2011/08/31/github-flow.html Scott "Gizzard" Chacon: GitHub Flow]
+* [http://continuousdelivery.com/2011/07/on-dvcs-continuous-integration-and-feature-branches/ Jez Humble: On DVCS, continuous integration, and feature branches]