{"action":"created","issue":{"url":"https://api.github.com/repos/iojs/io.js/issues/725","labels_url":"https://api.github.com/repos/iojs/io.js/issues/725/labels{/name}","comments_url":"https://api.github.com/repos/iojs/io.js/issues/725/comments","events_url":"https://api.github.com/repos/iojs/io.js/issues/725/events","html_url":"https://github.com/iojs/io.js/issues/725","id":56687353,"number":725,"title":"Stability Policy/Statement","user":{"login":"mikeal","id":579,"avatar_url":"https://avatars.githubusercontent.com/u/579?v=3","gravatar_id":"","url":"https://api.github.com/users/mikeal","html_url":"https://github.com/mikeal","followers_url":"https://api.github.com/users/mikeal/followers","following_url":"https://api.github.com/users/mikeal/following{/other_user}","gists_url":"https://api.github.com/users/mikeal/gists{/gist_id}","starred_url":"https://api.github.com/users/mikeal/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mikeal/subscriptions","organizations_url":"https://api.github.com/users/mikeal/orgs","repos_url":"https://api.github.com/users/mikeal/repos","events_url":"https://api.github.com/users/mikeal/events{/privacy}","received_events_url":"https://api.github.com/users/mikeal/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":7,"created_at":"2015-02-05T15:49:25Z","updated_at":"2015-02-05T20:59:23Z","closed_at":null,"body":"Something that is coming up over and over again is fear about the stability of io.js between versions.\r\n\r\nBecause 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.\r\n\r\nAs 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.\r\n\r\nHere'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.\r\n\r\n## Stability Policy\r\nio.js will not break backwards compatibility in the core JavaScript API.\r\n\r\nio.js will will continue to adopt new v8 releases. \r\n* When the v8 C++ API causes breakage that can be handled by `nan` \r\nthe *minor* version of io.js will be increased. \r\n* When the v8 C++ API cases breakage that can NOT be handled by `nan` \r\nthe *major* version of io.js will be increased.\r\n* When new features in the JavaScript language are introduced by v8 the \r\n*minor* version number will be increased. TC39 has stated clearly that no \r\nbackwards incompatible changes will be made to the language so it is \r\nappropriate to increase the minor rather than major.\r\n\r\nNo new API will be added in patch releases. \r\n\r\nAny API addition will correspond to an increase in the minor version."},"comment":{"url":"https://api.github.com/repos/iojs/io.js/issues/comments/73126877","html_url":"https://github.com/iojs/io.js/issues/725#issuecomment-73126877","issue_url":"https://api.github.com/repos/iojs/io.js/issues/725","id":73126877,"user":{"login":"mikeal","id":579,"avatar_url":"https://avatars.githubusercontent.com/u/579?v=3","gravatar_id":"","url":"https://api.github.com/users/mikeal","html_url":"https://github.com/mikeal","followers_url":"https://api.github.com/users/mikeal/followers","following_url":"https://api.github.com/users/mikeal/following{/other_user}","gists_url":"https://api.github.com/users/mikeal/gists{/gist_id}","starred_url":"https://api.github.com/users/mikeal/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mikeal/subscriptions","organizations_url":"https://api.github.com/users/mikeal/orgs","repos_url":"https://api.github.com/users/mikeal/repos","events_url":"https://api.github.com/users/mikeal/events{/privacy}","received_events_url":"https://api.github.com/users/mikeal/received_events","type":"User","site_admin":false},"created_at":"2015-02-05T20:59:22Z","updated_at":"2015-02-05T20:59:22Z","body":"> No new API will be added in minor releases.\r\n\r\nThat was a typo, should have been `patch`, fixed now.\r\n\r\n>  *cadence* of releases\r\n\r\nI 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.\r\n\r\n> We don't always know for sure that a change will not break existing users.\r\n\r\nSure, 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.\r\n\r\nHaving a strong goal is important, it's what motivates us and the community to step up and create better tooling like this.\r\n\r\n> 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.\r\n\r\nI 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.\r\n\r\nI 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.\r\n\r\nIMO `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.\r\n\r\n> stable and unstable channels and such\r\n\r\nAgain, 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.\r\n\r\nI 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.\r\n\r\nOne 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.\r\n\r\nI 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."}}