[Draft] Semantic Versioning for TypeScript Types #3
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
dfreeman
reviewed
Mar 23, 2021
text/0000-semver-for-ts.md
Outdated
|
|
||
| For TypeScript packages be good citizens of the broader, semantically-versioned JavaScript ecosystem, package authors need a useful definition of SemVer for TypeScript’s type system. | ||
|
|
||
| This is somewhat more complicated than in other languages, even those other statically-typed languages with language-level SemVer guarantees (such as [Rust][rust-semver] and Elm), because TypeScript has an unusually flexible type system. In particular, its [structural type system][structural] means many more kinds of both breaking and non-breaking changes are possible than in languages with a [nominal type system][nominal]. Accordingly, this document proposes a definition of SemVer which accounts for the extra flexibility afforded by these features. |
There was a problem hiding this comment.
I was going to suggest linking to Elm's semver handling here, but it seems like the zillion blog posts extolling its virtues all link to the now-defunct elm-package repo 🙃
There was a problem hiding this comment.
I actually asked on the forum for that exact reasons. 🦗 🦗🦗🦗🦗
text/0000-semver-for-ts.md
Outdated
|
|
||
| - If an interface is defined as having a property which is *not* part of the public API of the runtime object, or if an interface is defined as *missing* a a property which the public API of the runtime object does have, this is a bug. | ||
|
|
||
| As with runtime bugs, authors are free to fix type bugs in a patch release. As with runtime code, this may break consumers who were relying on the buggy behavior. However, as with runtime bugs, this is well-understood to be part of the sociotechnical contract of semantic versioning. |
There was a problem hiding this comment.
"Sociotechnical Contract" would be a solid name for a prog-rock band 😄
There was a problem hiding this comment.
I would 1000% listen to that band. I think I must have been reading Zeynep Tüfekçi when I wrote that.
This RFC proposes a definition of [Semantic Versioning][semver] for managing changes to TypeScript types, including when the TypeScript compiler makes breaking changes in its type-checking and type emit across a “minor”release.(Note that this RFC addresses *only* type checking and type emit, *no t* the “transpilation”mode of the TypeScript compiler.) [semver]: https://semver.org While this RFC is being authored in the context of Ember.js’ [adoption of TypeScript as a first-cl ass supported language][RFC], its recommendations are intentionally general, in hopes that th ese recommendations can be widely adopted by the broader TypeScript community. [RFC]: emberjs#724
chriskrycho
force-pushed
the
semver-for-ts
branch
from
46f2fa2 to
aa0fd79
Compare
|
Open as emberjs#730! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Introduce a policy for semantic versioning for TypeScript types, which accounts for both the details of TypeScript's structural type system and the need to absorb breaking changes in the TypeScript compiler. Adapted from the work done at typed-ember/ember-cli-typescript#1158 – with significant changes made to the recommendations around the supported compiler version policy (recommending two alternative approaches) and adding details around strictness.
Rendered text 📄
tscversion support policy recommendations