doc: first pass at stability policy #21
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -183,6 +183,80 @@ By making a contribution to this project, I certify that: | |
|
|
||
| (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. | ||
|
|
||
| ## Stability Policy | ||
|
|
||
| The most important consideration in every code change is the impact it will have, positive or negative, on the ecosystem (modules and applications). To this end, all Collaborators must work collectively to ensure that changes do not needlessly break backwards compatibility, introduce performance or functional regressions, or negatively impact the usability of the Project on any of the platforms officially targeted for support by the Project. The TSC is responsible for determining the list of supported platforms. | ||
|
|
||
| When discussing stability, it is important to first review Node.js' layered architecture: | ||
|
|
||
| ``` | ||
| +---------------------------------------------------+ | ||
| | Module and Application Ecosystem | | ||
| +---------------------------------------------------+ | ||
| | | | | | | ||
| | | +----------------------+ | | ||
| | | | Native Abstractions | | | ||
| | | | for Node.js | | | ||
| | | +----------------------+ | | ||
| | | | | | | ||
| +----------------+ | | | / | ||
| | Node.js Core | | | | / | ||
| | Library API | | | | / | ||
| +----------------+ | | | / | ||
| | js impl | | | | / | ||
| +----------------+ | | | / | ||
| | | | | / | ||
| +--------------------------------------+ |/ | ||
| | Node.js Application Binary Interface | | | ||
| +--------------------------------------| | | ||
| | C/C++ impl | | | ||
| +--------------------------------------+ | | ||
| | | | ||
| +---------------------------------------+ | ||
| | Dependencies: v8, libuv, openssl, etc | | ||
| +---------------------------------------+ | ||
| ``` | ||
|
There was a problem hiding this comment. Just a nit, but, should only be one line above NAN :) There was a problem hiding this comment. Nan should be used twice as much? Lol... Thanks will fix
There was a problem hiding this comment. (It should be used twice as much as direct C++ APIs though. :P) |
||
|
|
||
| Node.js currently builds on top of several key dependencies including the V8 Javascript engine, libuv, openssl and others. The Node.js Application Binary Interface provides critical functionality such as the Event Loop which critical to how Node.js operates. The Node.js Core Library is the primary interface through which most Modules and Applications built on top of Node perform I/O operations, manipulate data, access the network, etc. Some modules and applications, however, go beyond the Core Library and bind directly to the Application Binary Interface and dependencies to perform more advanced operations. The Native Abstractions for Node.js (`nan`) is binary abstraction layer used to buffer module and application developers from changes in the Application Binary Interface and Dependencies. | ||
|
|
||
|
|
||
| Due to the existing layering, modules and applications are sensitive not only to changes in the Core Library API, but the Application Binary Interface and dependendencies as well. | ||
|
|
||
| Any API *addition* to either the Node.js Core Library API or Application Binary Interface must result in a *semver-minor* version increase. | ||
|
There was a problem hiding this comment. So, the current io.js Stability Policy states that changes to the ABI that can be handled by However, in practice this is not what we've done and have been more conservative. Towards the end of v8's last cycle they took a very minor change that altered the ABI. We kept that change out, it was quite trivial and we all agreed wasn't worth forcing everyone to suffer an addon recompile. I remember that in the TC discussion about that change many TC members felt that if we're going to force an addon recompile it should only be on a major version bump. This is worth discussing in the next meeting as well, I think there are some differences of opinion here. There was a problem hiding this comment. Perhaps something like "Any modification to the Application Binary Interface or Dependencies that would require module or application developers to recompile must result in a semver-major version increase." There was a problem hiding this comment. @jasnell that might be good but I would hold off on making the change until we discuss it on Thursday. Let's put this down as an agenda item :) |
||
|
|
||
| Any *backwards incompatible* change to either the Node.js Core Library API or Application Binary Interface must result in a *semver-major* version increase. | ||
|
|
||
| Issue: Should any modification to the ABI or Dependencies that requires module or application developers to recompile force a *semver-major* change? | ||
|
There was a problem hiding this comment. Policy for this in io.js is There was a problem hiding this comment. @Fishrock123 that's the policy but in practice we've held off on changes in a minor that would do this and that was driven by the TC so we may want to revisit it. There was a problem hiding this comment. I think if we could get over our psychological hurdle against minting new version numbers then semver-major makes the most sense. But right now we're hesitant to release a 2.0.0 and thus missing ABI changes (notably a floating patch on top of V8!) that need to be made. There was a problem hiding this comment. Agreed. I think we'll get there soon tho |
||
|
|
||
| APIs and default behaviors in the Node.js Core Library, Application Binary Interface, Dependencies and nan must not change within LTS Releases unless the change is required to address a critical security update. | ||
|
|
||
| Note that default or assumed behaviors and values are exposed via the API, ABI or Dependencies are considered to be part of the API. A change in a default value, for instance, counts as an API change as modules and applications may be written to assume certain defaults and could be broken. | ||
|
There was a problem hiding this comment. Not 100% sure this is always the case. I.e. Certain There was a problem hiding this comment. Ya, this makes me wonder what constitutes a "default value." For instance, error message text defaults were change in libuv, that wasn't a major bump. There was a problem hiding this comment. This also puts changes like this one in a weird position – technically this breaks existing behavior and should be semver-major, but we're nearly 99% sure that no one is relying on the ability to redefine constants, so it's in at patch level. On the other hand, we were nearly 99% sure that making There was a problem hiding this comment.
IMO it should have been major and probably would have been if we knew ahead of time that it would break this. There was a problem hiding this comment. Perhaps: "Default or assumed behaviors that, if modified, could cause modules or applications to break are considered part of the API." This would exclude things like error messages which are generally informational but would catch such things as, say, openssl default cipher suites, etc. There was a problem hiding this comment. I think it's more practical to use the browser-esque standard of "this is technically backward incompatible but in practice should not be." E.g. transitioning from throwing an error to not throwing an error could be backward incompatible for code that depends on the error being thrown, or changing a message string could be backward incompatible for code that parses the string, or removing a underscore-prefixed API could be backward-incompatible for code that abuses it. But in reality those cases should be rare and are allowed to break. @petkaantonov sums this up well in nodejs/node#1356 (comment) There was a problem hiding this comment. That's a good point @domenic. I can continue to tweak the wording on this particular bit |
||
|
|
||
| ### Dependency Stability | ||
|
|
||
| #### JavaScript Support (V8) | ||
|
|
||
| Node.js will adopt new V8 releases as quickly as practically feasible. For LTS Releases, the version of V8 shipped must be supported and fully operational on all platforms officially targeted for support. | ||
|
There was a problem hiding this comment. We may want to explicitly state that the ABI cannot change on LTS releases unless it is required for a critical security update. LTS consumers will definitely not be expected to have to recompile their addons. There was a problem hiding this comment. How about just reverting ABI changes to LTS releases? There was a problem hiding this comment. "the version of V8 shipped must be supported and fully operational on all platforms officially targeted for support" unless you are shipping new LTS (and removing old ones) every six weeks, I don't see how this is possible, since V8 versions older than the current one are not supported. There was a problem hiding this comment. "Supported" is perhaps the wrong word. When a new LTS is cut, the version of V8 shipped should build / be functional / not introduce any regressions for any of the officially supported platforms. It's really a stability requirement. If we ship an LTS with a V8 that works on Platforms A, B, and C one week, we shouldn't ship an LTS with a V8 that only works on Platforms A and B a few weeks later unless Platform C is removed from our officially supported platforms. There was a problem hiding this comment. That said, we may want to refine some of the language around "Officially supported platforms" There was a problem hiding this comment. Yes, please remove the word "supported" then, in reference to old V8 versions. |
||
|
|
||
| When V8 ships a breaking change to their C++ API that can be handled by `nan` there will be a *semver-minor* version increase. | ||
|
|
||
| When V8 ships a breaking change to their C++ API that cannot be handled by `nan` there will be a *semver-major* version increase. | ||
|
|
||
| When new features in the JavaScript language are introduced by V8, there will be a *semver-minor* version increase. 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 the *major*. | ||
|
|
||
| Pull Requests that introduce post-ES5 mechanisms into the Node.js Core Library API require TSC review and approval. If landed, such changes must result in a *semver-major* version increase. However, Pull Requests may introduce post-ES5 mechanisms into the *internal* JavaScript implementation of the Core Library API so long as those mechanisms do not "bleed out" through the API. | ||
|
There was a problem hiding this comment. Isn't this harmful? Why would these be There was a problem hiding this comment. This is for things like adding promises into the core API. It's been a
There was a problem hiding this comment. We haven't done this yet, and have no plans to, so I don't quite see why we are already creating a policy around it. You could characterize the existing policy as "we aren't adding ES5 features to the core API" and that will remain true until we do, at which point we'll be far more informed and can write a better policy. I'm also concerned with how widely defined "post-ES5 mechanism" could be. For instance, the There was a problem hiding this comment. Extra review is fine for now, but that shouldn't force a non-breaking change to be Also, the majority of likely additions in this area are not as radical as Promises. There was a problem hiding this comment.
I'm not actually sure that is the current state of things. There have been a lot of places where Symbols have been recommended by TC members recently. There was a problem hiding this comment. @domenic I've iterated on this language. Can you check the current version and see if it works for you? There was a problem hiding this comment. No, it does not work for me. Adding a feature should not bump the major version if that feature is added in a backward compatible way. Gating on language versions (which are fictional constructs anyway) doesn't change this. There was a problem hiding this comment. Oh, I'm sorry, I didn't realize the iteration was in a follow-up PR. It does look better there. There was a problem hiding this comment. No worries, the edits are coming rather quickly as I'm trying to get a stable draft in by today to give everyone time to review before tomorrows call. I'm trying to keep at most one active PR at a time so if you look at the master and see an open PR, the most recent edits are in the PR. If there's no open PR, then the master is the latest. I definitely appreciate you jumping in with comments. It's very helpful |
||
|
|
||
| #### Other dependencies | ||
|
|
||
| Other dependencies such as OpenSSL, libuv and http-parser are handled similarly. | ||
|
|
||
| Node.js will continue to adopt new dependency releases as often as practically feasible. | ||
|
|
||
| When a dependency ships a breaking change to their API, if that change can be abstracted by the Node.js Application Binary Interface such that module and application developers can be isolated from the change without breaking existing applications, there will be a *semver-minor* version increase. | ||
|
|
||
| When a dependency ships a breaking change to their API that cannot be abstracted by the Node.js Application Binary Interface, there will be a *semver-major* version increase. | ||
|
|
||
| When dependencies introduce additional functionality that does not break backwards compatibility in any way, there will be a *semver-minor* version increase. | ||
|
|
||
| ## A Few Open Questions | ||
|
|
||
| 1. What about things like http_parser and libuv? Does it make sense to see about bringing each into the foundation as their own projects? | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is great wording, much better than what I wrote in our Stability Policy :)