Stability Policy/Statement

[mikeal]

Something that is coming up over and over again is fear about the stability of io.js between versions.

Because we made such a big jump in functionality from 0.10 to 1.0 people fear that we broke reverse compatibility. The increased pace of releases only feeds in to the fear that we are going to continually break people's applications and parts of the ecosystem.

As we build the roadmap it's important that we have a clear policy about what we will and will not break and what signals we intend to give in those releases to signal the changes.

Here's a starting point, I'm sure it will drum up a bunch of feedback and we will need to continue to iterate on it.

Stability Policy

io.js will not break backwards compatibility in the core JavaScript API.

io.js will will continue to adopt new v8 releases.

• When the v8 C++ API causes breakage that can be handled by nan
  the minor version of io.js will be increased.
• When the v8 C++ API cases breakage that can NOT be handled by nan
  the major version of io.js will be increased.
• When new features in the JavaScript language are introduced by v8 the
  minor version number will be increased. TC39 has stated clearly that no
  backwards incompatible changes will be made to the language so it is
  appropriate to increase the minor rather than major.

No new API will be added in patch releases.

Any API addition will correspond to an increase in the minor version.

Long Term Support

iojs intends to support old version as long as community members are fixing bugs in them. As long as people at committing bug fixes and improvements that don't change or add API we will push patch releases.

legacy-v8

When the v8 team stops supporting a version that a prior iojs release depends on we will create a branch in iojs/legacy-v8. This branch will be used to continue to land fixes in unsupported lines of v8. These branches will be pulled in to future patch releases of iojs.

[mikeal]

Also, we might want to consider vendoring nan and shipping it with io.js.

[Fishrock123]

io.js will not break backwards compatibility in the core JavaScript API.

I think this is harmful long-term. See the entire promises co-existence discussion.

Saying everything will never change locks you into a position where everything you do is stuck as legacy forever.

[mikeal]

@Fishrock123 the thing is, that statement is already pretty true. We still can't even remove the sys module even after years of deprecation. If promises are added to the current API it will have to be done in a compatible way and will be considered an API addition not a backwards incompatible change.

If we ever wanted to move to a better promise-centric API we would probably do that along with support for the new modules spec and all the API changes would only be accessible through new-style modules which would make that an API addition and not a backwards incompatible change.

We've got an ecosystem of 130K modules, it'll be 200K before the end of the year. Any backwards incompatible change will break tens of thousands of modules, not to mention all the applications that rely on them. At this point in the projects maturity it just isn't conceivable that we can make real backwards incompatible breaks.

[mikeal]

From the Tracing WG: Do we consider the tracing probe endpoints part of the public API and as such removals & additions effecting the major/minor bumps? What is our policy on compatibility changes here?

[Qard]

I would say moving the probes from core to userland should be allowed, but in a major version bump. The primary users are enterprise that care about that functionality a lot, and moving the parts out of core may require changes to their tooling.

[chrisdickinson]

io.js will not break backwards compatibility in the core JavaScript API.
@Fishrock123 the thing is, that statement is already pretty true. We still can't even remove the sys module even after years of deprecation.

I understand this sentiment, but in practice that's not accurate:

• We don't always know for sure that a change will not break existing users. The potential for unforeseen consequences is great. Committing to something so hard-line would be disingenuous to our users.
• There are cases where API have to break for the health of the platform. The addition of proper keep-alive support, the migration from streams2 to streams3, and the eventual removal of domains.
• In other cases – like the removal of sys – it's a matter of "is it worth it to break backwards compatibility for this one change?" In many cases, the answer is no. However, if we do have to bump a major version, the value proposition might change and we can revisit that sort of breakage. If we do that, we should commit to being very upfront about what will break far in advance – adding these sorts of features to a v2 milestone wouldn't be a bad idea, and making sure that we limit the number of breaking changes to a easily definiabl

In short, I think the best we can promise is that we will be very conservative about breaking changes, and message them to community (along with remediation approaches) far in advance of the change, with specific steps to prepare for the change.

so, we might want to consider vendoring nan and shipping it with io.js.

100% yesplease.

No new API will be added in minor releases.

By this, do you mean no "net new" modules? For instance, if we added a tracing module, that would require a major version bump? If so, I'm not sure I agree – it seems to me like that could still fall under a minor release.

---

In addition, I think having a stance on the cadence of releases is important as well – node got away with ad-hoc releases without fatiguing the community primarily because the releases were so infrequent, IMO. This ties back into the releases document I worked on, and letting the community know that there will be "LTS" or stable releases that bugfixes will be backported to, and at what rate those releases will be made available. I've taken a bit of a break from working on that doc. I'll revisit it this weekend and see about addressing concerns / simplifying it. Getting to see the release process as it exists now should help inform the document.

[mikeal]

No new API will be added in minor releases.

That was a typo, should have been patch, fixed now.

cadence of releases

I would like to entirely separate the issue of stability from cadence. We should state our policy for stability, what we are willing to do and not to do and what version number changes will correspond to those changes. If we can't comply with those commitments then the cadence will drop and we will have to invest in better tooling and automation in order to pick back up the cadence while still complying with our stability commitments.

We don't always know for sure that a change will not break existing users.

Sure, it's software, we never know anything with 100% certainty, what this says is that if/when we do that it's a bug and entirely unintentional and that will will take every measure available to fix it and ensure it doesn't happen again. If it happens often we'll have to change our release/automation strategy to better detect issues like this or slow down releases. We do almost nothing now (although still more than we did under node.js), there are 130K modules we could automate the testing of to see if there are changes from one version to the next.

Having a strong goal is important, it's what motivates us and the community to step up and create better tooling like this.

There are cases where API have to break for the health of the platform. The addition of proper keep-alive support, the migration from streams2 to streams3, and the eventual removal of domains.

I don't think keep-alive support was a breaking change. request didn't need any code changes when it landed and it touches pretty much the whole http API.

I think that streams2 is exactly what a document like this is trying to assure people we aren't going to do. streams3, as I understand it, fixes more compatibility problems than it causes.

IMO domains will print a very annoying error for years and even then we probably will still keep it around for fear of breaking some applications. But hey, I'd love to be proven wrong.

stable and unstable channels and such

Again, I think this is something that will need to continue to evolve. The goal of these channels is to increase confidence that what we are saying (this doesn't break in these ways) is actually true.

I have big concerns about allowing intentional breaks in the JS API in major version bumps. We don't know for sure yet how often we'll have to increment the major version based on v8 changes but let's be really pessimistic and say that every 6-8 weeks we have to do a major version bump. So now our version number is about as meaningless as Chrome's is at messaging big changes. Slipping a JS API change which has a far wider reach in to such a release and would be difficult if not impossible to message properly.

One idea I had for a selection of big changes (like supporting ES6 Modules but giving them a more ES6 centric API instead of the current one) we would have a branch/channel for it for a long time, something like iojs-NG (Next Generation) and we get people experimenting with that channel for a long time before we announce an integration date and a version number it would land in. But even this is something we should, and I believe we can, do in a backwards compatible way without breaking any existing JS modules.

I don't actually think that dedicating ourselves to not breaking backwards compatibility in the JS API is that huge of a burden. It's the same burden TC39 has and they've mitigated it by coming up with creative ways to separate the new from the old so that the new can be handled differently, we can do the same.

[bnoordhuis]

Also, we might want to consider vendoring nan and shipping it with io.js.

I don't think that's going to work, at least not in the near term. Best case, symbol clashes would happen when io.js ships nan 1.5 but an add-on depends on nan 1.4. Worst case, there are no symbol clashes but the add-on quietly starts doing the wrong thing.

From the Tracing WG: Do we consider the tracing probe endpoints part of the public API and as such removals & additions effecting the major/minor bumps? What is our policy on compatibility changes here?

The Linux kernel counts tracepoints as part of the public API and it occasionally really hampers progress. I would advocate minor version bumps only with no promise of stability for now.

[taoeffect]

Could we please get some sort of official stance via a blog post or something? (I take it that's what this issue is trying to get done?)

I couldn't find information as to what's going on with Streams 3 and the other changes introduced in nodejs 0.12 and how it relates to io.js.

Without an official statement there is the very real danger of FUD spreading. I, for example, am honestly concerned about potential continued divergence of the two projects. It could split the node community in two in a way that is bad for everyone.

Request: reassuring words backed by reassuring actions, plz.

[mikeal]

@taoeffect we only have the ability to talk about what we intend to do. In regard to divergence between the projects we can't speak to what Joyent will decide to do or what direction they might take things. This policy is an attempt to come to a consensus then message and implement a policy or io.js. We have no control over what Joyent's policy might be or how closely they might follow it.

[taoeffect]

@mikeal Well then what does io.js intend to do with regards to new nodejs features and API changes?