doc: API stability policy #50
Conversation
re: #37 Expanded language around
|
While it isn't what I want the policy to be, it is much clearer than it was which is good. |
| APIs and default behaviors in the Node.js Core Library, Application Binary Interface, Dependencies and binary abstractions must not change within LTS Releases unless the change is required to address a critical security update. | ||
| The Node.js Core Library API, Application Binary Interface and Binary Abstraction layer each expose methods, events, behaviors and default values that together comprise the implicit Node.js "Public API". This "Public API" is used by application and module developers and changes will have direct impact on the Community. | ||
|
|
||
| Methods exposed by the API can have either strongly or weakly types input parameters and return values. Methods may also throw any number of exceptions or trigger certain sequences of events or side effects. When such types, exceptions, events or side-effects are *documented*, they become part of the Node.js *Explicit API*. |
There was a problem hiding this comment.
weakly types input parameters
typed
|
@arb nothing is set in stone. how would you change it? |
fixing typos and refining the implicit api exceptions.
|
@Fishrock123 better after the new commit? |
|
I agree with @cjihrig - if you are using a public API method in an undocumented or unexpected way, that's on you when it breaks. There shouldn't be a major bump when you add validation or change the function so it no longer works the undocumented way. There is a lot of code that lingers around because people started using something wrong and now it's in there for good... Seems like that is not the prevailing opinion though. |
|
Yeah that's better. |
|
@arb... I tend to agree with both points of view which is why this attempts to add some wiggle room for exceptional cases. |
It's easy to say things like this but the reality is that if enough people are using/depending on an API, documented or not, we can't break it. If a change breaks a significant portion of the ecosystem it won't make it in, there's no moral or technical high ground we can find that justifies breaking the ecosystem. This is why @chrisdickinson has been trying to find ways of creating truly "internal only" modules so that we don't continue to put ourselves in a position where we have to support what was meant to be a private internal API. |
|
(Speaking of which, io.js now has support for internal modules.) |
|
Merging this change. Keep in mind that this can be iterated on further. |
|
|
||
| Backwards incompatible changes to *Explicit* APIs that have previously been included in a Release *must* follow a clear and predictable deprecation process in which the existing documented API: (a) is clearly marked for deprecation and (b) can change only after the next *semver-major* version increase. | ||
|
|
||
| Backwards incompatible changes to *Implicit* APIs that have been included in a Release *should* be handled the same as *Explicit* API changes. However, exception to this rule can be allowed if: (a) the proposed change can be reliably demonstrated to have minimal impact *in practice*, (b) the proposed change is intended to reconcile *implemented* behavior with *documented* behavior (i.e. the documentation says one thing but the code does another and either the code or documentation need to be updated), (c) it is clear that the Implicit API being modified had originally been intended for internal use as part of the underlying implementation as opposed to being targeted at developers, or (d) it can be demonstrated that the Implicit API never worked correctly to begin with. |
There was a problem hiding this comment.
Nits, belatedly:
(b) the proposed change is intended to reconcile implemented behavior with documented behavior (i.e. the documentation says one thing but the code does another and either the code or documentation need to be updated)
Documentation is a derivation of code, not the other way around. Changing code to match docs – especially if the change causes breakage – should follow the same process as explicit API changes. IOW: Changing docs to match behavior stands to break nobodies code, changing code to match docs can break code – which should be avoided without a deprecation cycle.
(c) it is clear that the Implicit API being modified had originally been intended for internal use as part of the underlying implementation as opposed to being targeted at developers
I'm thinking here of things like _readableState, or _events within EventEmitter – those things, while private implementation details, are so widely used throughout the ecosystem that any change to those should probably be preceded by a lengthy deprecation cycle (or polyfilling those features back in.)
|
LGTM, with a few nits. @arb: the end result is the same – if you're using implicit APIs, you may eventually have to change your code. Core has to move more slowly in order to get to that point, though, because so much (otherwise well-intentioned) code relies on those implicit APIs, and those dependencies can be incredibly distant from any given user's control. Deprecation cycles give the community the chance to identify problem modules in their dep trees and put pressure on those modules to update, or to create an alternative to that module. |
re: #37
Expanded language around the API stability policy