This repository has been archived by the owner on Apr 18, 2018. It is now read-only.
doc: few additional api stability nits #52
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
| 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 the proposed change can be reliably demonstrated to have minimal impact *in practice* and either: | ||
|
|
||
| (a) the proposed change reconciles *documented* behavior with *implemented* behavior (i.e. the documentation needs to be updated to accurately reflect how the code actually works); |
There was a problem hiding this comment.
I'm a bit confused by this wording – in this case I'd say that our "explicit API" (via the docs) should be changed. Given that explicit APIs are a strict subset of our implicit APIs, docs that lie aren't part of the explicit API, they're just lies :) Generally, we shouldn't change code to match docs, we should change docs to match code.
There was a problem hiding this comment.
hmm... I think we're saying the same thing just in two different ways.
There was a problem hiding this comment.
AH! Okay, yes, I was definitely misreading that. Disregard. +1000!
|
LGTM! |
jasnell
added a commit
that referenced
this pull request
Apr 10, 2015
doc: few additional api stability nits
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Per #50 (comment).