Release Versioning

[AlinaNova21]

While listening to the TC meeting today, I had a few thoughts on versioning. Someone in IRC suggested writing an Issue.

My thoughts are that there should be a stable version, ex 1.0.2, 1.0.3 with current V8 release, then a -beta channel tracking latest V8
Such as:
IOJS: V8
1.1.x: 41
1.2.x: 42
etc

[bnoordhuis]

/cc @iojs/tc @domenic

I'm partial to -canary or -next style of development but it shouldn't turn into another node.js v0.11, a dumping ground for new features, without a release date.

If we're going to follow Chrome's release cadence, we can turn -next into the 'io.js from six weeks in the future': the next stable V8 and any pull requests that warrant a minor or major version bump.

Six weeks time is short enough that contributors shouldn't get demotivated. It's also short enough that you won't get a massive delta like with node.js v0.10 and v0.11, where everything has changed so much that it's basically impossible to merge one into the other.

[bnoordhuis]

Forgot to add, that would also carry over to projects like nan: nan-next would target the upcoming stable V8 and be ready and tested when io.js is released. /cc @kkoopa

[AlinaNova21]

@bnoordhuis I agree with your comments, the whole 0.10 and 0.11 difference is annoying, I like Chrome (And V8 since they are directly linked) release cycles. I even ran canary builds for a while, went back to stables after a few rather buggy releases and just haven't switched back yet.
Having the -canary or -next branch as you suggested would work really well as preparations for the next release could be implemented and test well before the 6 week releases.
There are some (like me) who like running bleeding edge releases for the new features.

[Qard]

+1 on -next. Having one build that is built against latest stable V8 and another that is built against what is planned to be the next stable V8 would be good.

[trevnorris]

+1 on following the v8 release schedule. I believe they would like us to do the same.

[trevnorris]

Though I don't like bumping major versions every 6 weeks. Instead upgrading v8 should be a minor version (i.e. API changes in dependencies shouldn't require upgrading major versions).

[AlinaNova21]

👍 @trevnorris That does make more sense, major versions would be because of major API changes in io.js rather than V8

[chrisdickinson]

@trevnorris if the v8 change doesn't break the C++ API for addons, then yes, we should bump minor (or even patch!) for new v8 releases. However, if it does break addons we should reflect that in our version bump.

[rvagg]

@bnoordhuis what do -canary or -beta version descriptors look like? and under the proposal would this preclude merging anything in to the main release branch that would bump minor or major but leave them all for the 6 weekly bump?

[rvagg]

(sorry, to clarify my request, I'm looking for some example versions in a sequence, do we have 1.1.0-beta01, 1.1.0-beta02, 1.1.0-beta03, etc. until we reach the 6 week point and do a proper 1.1.0?)

[domenic]

Here is more or less what I took away from the TC meeting. Let me know how it sounds. When writing it down, it is a bit complicated.

• There are at any times two main version trains, iojs@x.y.z and iojs@r.s.t-canary.
• They probably have different logos, like Chrome vs. Chrome Canary or Ember vs. Ember Canary.
• At any given time, iojs@r.s.t-canary contains some combination of:
  • Definitely, V8 version current-chrome + 1.
  • Possibly, changes to io.js that we don't feel comfortable pushing to the stable train yet.
• The relation between r.s.t and x.y.z depends on whether:
  • The V8 version bump introduces new features or backward-incompatible changes (the latter would only be API changes, not JS changes)
  • The changes to io.js include new features or backward-incompatible changes
• V8 rolls every six weeks, but we might release a new version of the main stable io.js more often than that. (Changing x.y.z.) In this case we will also need to renumber canary.
• For the next six weeks, we are already ahead of Chrome stable: we are on V8 4.1 which corresponds to Chrome 41, whereas Chrome 40 was released today. To synchronize:
  • There is no canary for the next six weeks (or at least if there is, it does not contain a newer V8).
  • After six weeks are up and Chrome 41 is released, we keep stable on V8 4.1, and release a canary with V8 4.2.

Potential points of discussion:

• Is only two trains enough, or do we want three (Ember-style stable/beta/canary), or four (Chrome-style stable/beta/dev/canary or Firefox-style stable/beta/aurora/nightly)? If we have more than one then we can test V8 changes even more in advance.
• What is the relation to nightly? Maybe, canary = nightly + V8 upgrade?
• Maybe we want to avoid the hassle of figuring out r.s.t, and say that r.s.t = x.y.z always, and hopefully the -canary suffix is enough to make people realize they're not in semver land anymore?

[timoxley]

The more surface area represented under a semver version, the less useful it is, and the harder it is to get right. If you change the JS api and bump the major, this may convey zero meaningful information for an addon developer, and vice versa.

What if io.js simply uses two versions? One which represents the C++ API for addons, and one for the JS API?

[rvagg]

Conversely, the more surface represented by the versioning scheme the more confusing it will be for everyone. "I'm using io.js v1.2.1+1.0.5"

The NODE_MODULE_VERSION macro is the effective "breaking" versioning scheme for addon developers, I'm not sure we need to complicate things too much beyond that because.

[chrisdickinson]

@timoxley the C++ addon layer breaking means that many popular packages will have to update – so even if you're not personally concerned with that breakage at a JS level, chances are you may be dependent (indirectly) on a package that is. Put another way, every package npm ecosystem has an implicit "node": "^N.X.X" dependency that, within a given application, must dedupe to a single version at the top level for the application to work.

---

Re: Canary builds: it seems like there are a few things interwoven here:

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. There may be some disagreement here:
   1. We want to roll in the current stable V8 every 6 weeks OR
   2. 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 relatively easy to do (1). (2) entails that every time we release we're popping the last release off of the "release queue" out as the stable iojs, and pushing the new release into the top, and that the release queue has to be long enough to give folks enough early warning time to instrument and test the release. (3.1) entails that the V8 release would just be work done every 6 weeks, and pushed into the queue like any other work, while (3.2) would involve keeping a parallel version of the release queue around as a "canary" build.

The train release system, if it's to be effective, sets a maximum number of releases / time period, which is at odds with our desire to ad-hoc release at least weekly.

What if we set up two queues, and addressed the v8 canary in the second (closer to release) queue?

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

Thoughts on this?