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?

[YurySolovyov]

IMO it should be the least possible number of "channels".
x.y.z for stables and x.y+1.z for betas. If there are no major issues, every 6 weeks beta becomes stable.

Basically this is +1 to top post

[trevnorris]

@chrisdickinson I disagree. Based on release history you can pretty much guarantee that some aspect of the v8 user API will change between releases. Which means a new major version every 6 weeks. I don't think we should go down that path.

[chrisdickinson]

@trevnorris Why avoid a major version every 6 weeks if we're committed to using semver? If the concern is LTS releases, we would cut (or preserve) a new vN.x branch for those releases and backport patch-level commits. If the concern is that it would disrupt the flow of PRs to the v1.x branch, perhaps we should consider moving to master as the development branch and only cutting major version branches once we decide to support them long-term.

[trevnorris]

@chrisdickinson IMO the C++ API does not have the same priority as that of the JS API. The user needs to explicitly #include <v8.h> in their applications in order to use the V8 API. It's not ours. If that were the case then every dependency (openssl, http_parser, etc.) that the user can include should also affect the major version.

It has nothing to do with being committed to using semver. It has to do with the fact that we aren't breaking our API.

[mikeal]

Taking semver out of it for a second, to me there are two buckets of "breaking changes" in the v8 API: those easily covered by nan and those that are not. The second bucket being a much bigger deal. Now, do we want to say that nan is basically part of the "platform" and we're only going to increment major when a breaking change falls outside of what nan can handle, or do we just say "v8 API change means a major version change," I don't really care. Either way the messaging will be hard at first but within a year people will get used to it.

[chrisdickinson]

@trevnorris while the API isn't ours, our API depends on the user sending arguments using classes from their API.

Put in a hypothetical, userland-JS way: say I have a package that uses three.js, and its API requires parameters to be of type THREE.Vector3. When I take a breaking change from three, should I bump my major version? It's three's API that changed, not mine; but any packages that are passing the wrong version of Vector3 to my package will break. There's some nuance here – if the breaking change in three.js didn't touch any classes I require as parameters, for instance, but in general I would take a conservative approach and bump my major.

The major version is there to tell end users that code will likely have to change to adopt the new version of my package. In io.js terms, our consumers are the packages on npm. If we know that our changes will break any package on npm that take specific action to update, we should bump our major version to reflect that. If we say that nan is part of the platform, as @mikeal suggests, I'm more amenable to not bumping the major version (assuming packages depending on nan don't break), though I'm still a bit nervous about that – I prefer to be conservative and lean towards bumping major versions, personally.

[trevnorris]

@chrisdickinson If I had a module that depended on functionality from a third-party module I'd wrap it with my own functions to make sure I could maintain compatibility. We haven't done that with Node. Native modules in iojs are still a mess.

Also, consider that you're talking about the entire deps/v8/include/v8*.h. That will basically require a major version bump every 6 weeks. We should not be doing that. It will make changes to the much more used JS API completely invisible because of all the version'ing noise. So whatever agreement we need to come to in order to prevent that from happening, should happen.

[sam-github]

+1 on only bump the major because of a v8 API change when it can't be handled by nan.

I thought I heard a TC meeting where this was already decided on, is it still up for discussion?

It blesses nan, people are free to do anything else they want, but if they directly use v8 APIs, they are committing to dealing with breakage themselves ("ourselves"... I have code that doesn't use nan, and I'm OK with this). nan isn't distributed in-tree with node, but that's a distribution detail, its available.

[Fishrock123]

Closing in favor of #630