doc: add releases document detail release cycle

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/<resource>-v1.0.4-lts201401.<type>
+```
+
+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.