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

Co-authored-by: Jeremy W. Sherman <[email protected]>

Co-authored-by: Jeremy W. Sherman <[email protected]>

- incorporate `enum`, `const enum`, and `namespace`
- break it out into bullet points for easier digestion

Co-authored-by: Jeremy W. Sherman <[email protected]>

Per discussion with the Ember TS strike team, moving the design summary
to the top gives an easily-digestible and -comprehensible overview of
the recommendations in the doc for people just wanting to get the big
idea.

Thanks to @jeremy-w and @tjjfvi for this clarification.

As @RyanCavanaugh notes [here][1], the author of an API may intend that
a given function or method is allowed to return a wider type than the
"current" implementation at a given time allows. The type signature thus
should reflect the intent of the API, *not* merely its implementation.

[1]: emberjs#730 (comment)

@jeremy-w correctly [pointed out][1] that the presence of the playground
links suggests that the behavior is *observed* rather than *promised*.
Make explicit both that the playground links are not normative *and*
that since TS has no formal spec, the implementation is the source of
truth for the type system.

[1]: emberjs#730 (comment)

In order to support the upcoming addition of a discussion of variance,
and to make the flow of the document clearer, restructure subsections
under Defining Breaking Changes:

- Introduce a new level-3 section, "Changes to Types", to cover all
  the detailed analysis of changes to code, and which will be the
  natural home of the discussion of variance.
- Move the discussion of supported compiler versions into another new
  level-3 section "Compiler Considerations", which also subsumes the
  existing discussions of strictness and module interop.

This does not *quite* finish the RFC content: it still requires showing
the examples of kinds of things which type-level variance prevents us
from typing safely, and describing the workarounds. This is much
simpler than the explanation, though!

This was just a mental flub: it was always intended to be the latter,
and I just repeatedly typo'd it.