From c809b22b0ea288a2cf02d612edff125e4f01454b Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Tue, 27 Jan 2015 16:34:16 -0800 Subject: [PATCH] doc: add releases document detail release cycle Add a release cycle document covering use of semver, LTS releases, support releases, train system, and git branching model. --- doc/releases.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 doc/releases.md diff --git a/doc/releases.md b/doc/releases.md new file mode 100644 index 00000000000000..86e156f53be6c7 --- /dev/null +++ b/doc/releases.md @@ -0,0 +1,129 @@ +# Releases + +**GOALS:** + +1. We want to retain the ability to ad-hoc release at least weekly so we can retain project momentum. +2. We want a train system so that we can give folks guaranteed time to vet new releases. +3. We want to roll in the current *stable* V8 every 6 weeks **and** immediately cut a branch + that tracks the new *unstable* V8 through the course of the 6 week period. + +Semver makes it easy to do **(1)**. +**(2)** is slightly at odds with **(1)** since it artificially limits the number of releases per time period. +**(3)** is a separate issue from **(1)** and **(2)** and is best dealt with as an "alternate version" of the canary build. + +I propose the following release system: four release lines, "dev", "next", "next+v8", "stable." + +1. "dev" is able to be released ad-hoc, with any semver combination. +2. "next" samples "dev" releases weekly on a specified day (**Thursday, 12:00 PST**). The prior release +on "next" is promoted to "stable" at this time. +3. "next+v8" represents "next" plus the work necessary to integrate the unstable copy of V8. This work is reapplied +to each new "next" release. This release line is a canary for V8 + io.js changes, whereas "next" is *just* io.js +changes. +4. V8 stable releases happen every 6 weeks. At the six week point, the work to apply the new version of V8 is released +on the dev branch. "next" will adopt this work the following **Thursday**. "next+v8" will now represent the newest +unstable V8. + +The following week, the "next" line carrying the new stable V8 is released as stable. + +**An illustration follows:** + +``` + |<------ v8 stable = 0, beta = 1 ------>|<-- v8 stable = 1, beta = 2 ... + 0------W------W------W------W------W------W------W------W-----------------> time + dev | a bc d e fghi j k l m + | + next | c0 d0 i0 k0 l0 m1 + | + next+v8 | c1 d1 i1 k1 l1 m2 + | + stable | c0 d0 i0 k0 l1 m1 + V ^ ^ + | | + | v8 "1" lands in "stable" + | + v8 "1" hits "next" + v8 "2" hits "next+v8" +``` + +* **W** on the time axis represents "one week boundary". +* iojs releases are **letters**, they may represent any combination of `X.Y.Z`. +* v8 releases are **numbers** after a letter. +* "next" samples the latest "dev": every week it pulls in the last dev release for the week. +* "stable" pulls in the last "next" release weekly. +* "next+v8" represents "next" + the unstable version of v8 for this period. +* The week of (or after) the v8 release, the new v8 is merged into iojs and released on the dev line. In the above diagram, that release is represented as **m** on the dev line. +* "next+v8" starts reflecting the next unstable version of v8. +* We lag 1-2 weeks behind iojs-stable adopting chrome-stable's v8. + +-------------------------------- + +## Git Branches – "master" and "support" branches + +Currently we follow a `v1.x` scheme. This presents difficulties when merging changes that connotate a major version bump. + +Instead, we should move back to using **`master`** for development. When a major version is bumped, a `vN.x` branch should be +created for the old major version before appropriate metadata is changed and committed to master. The new `vN.x` branch is +a **support** branch. + +Only **patch-level** changes may be backported to **support** branches; that is to say, major branches will only receive +bug- and security- fixes after their release. We should keep a queue of support branches: no more than 2 support branches +should exist at any time. + +-------------------------------- + +## LTS Releases + +For longer-term support, we will designate certain support branches as "LTS" releases. These branches should be cut as `LTS-YYYY-MM`. +We should plan on releasing 2-3 of these per year, and plan on supporting the last 3 LTS releases, shifting them off as +new LTS releases are cut. This translates into a lifetime of about a year for a given LTS release. LTS branches should be thought +of as "long lived" support branches – all of the rules that govern what can be committed support branches apply to LTS branches. + +LTS releases should be selected *after* the fact – that is, from the available **support** branches, instead of in advance +of a new major version. + +Between the support branches and LTS releases, we can support users whose are able to upgrade every week, every 3-4 weeks, and +those who are only able to upgrade yearly. + +Distribution-wise, an LTS release should be available as follows: + +``` +https://iojs.org/download/lts/2014-01/v1.0.4/-v1.0.4-lts201401. +``` + +Ideally package maintainers will primarily package these releases, and package the "stable" release line as "iojs-weekly." + +--------------------------------- + +## Security Releases + +Security releases **may** bypass the queued release system and update every release at any time. + +--------------------------------- + +## Rolling back a bad "next" + +If the "next" version to be promoted to "stable" has known issues, it should be replaced by the following "next" release **without** +promotion. + +--------------------------------- + +## Semver + +### Major versions + +io.js follows semver. The given version number should matter less to humans and more to machines. If changes +in our codebase would cause new breakages in downstream code – or if we strongly *suspect* that they will – the major version +should be bumped. The following caveats apply: + +* Breakage due to code that is "sniffing" version information +* Breakage due to accessing bindings or private properties (any property prefixed with "\_"). +* New breakage in existing deprecated code. +* Native API incompatiblity **not covered** by NAN. + +Downstream code refers to packages and applications available in the npm ecosystem. It does not refer to projects embedding node. + +### Minor and patch versions + +Any change that *passes* the last releases' tests may be considered for a minor or patch release. If the changeset adds any new +APIs or parameters to existing APIs, it should be released as a minor version bump. Otherwise, it should be released as a patch +bump.