add type test docs/README

README.md

@@ -49,3 +49,50 @@ the user's browser.
 
 [`@glimmer/application-pipeline`]: https://github.com/glimmerjs/glimmer-application-pipeline
 [`@glimmer/resolution-map-builder`]: https://github.com/glimmerjs/resolution-map-builder
+
+## Tests
+
+### Type Tests
+
+The following packages are committed to maintaining stable Typescript types in
+addition to their JavaScript API:
+
+* `@glimmer/component`
+
+Any changes to their types, _including_ changes caused by upgrading the
+Typescript compiler, are covered under SemVer for these packages (e.g. breaking
+changes to types will require a new major version).
+
+In order to ensure we aren't making changes to types unintentionally, we have a
+set of tests for their public APIs in `/test/types`. These can be run with:
+
+```sh
+yarn build
+yarn test:types
+```
+
+In general, any new additions to the public types should be a new _minor version_,
+and removals of public APIs or changes to the versions of TS that are supported
+should be a _major version_. Corrections to existing types that are
+_not breaking_ (e.g. strictly equal to or wider than the current type) can be
+released in _patch versions_.
+
+To add a new API:
+
+1. Add it to any `hasExactKeys` statements that assert on the keys of a public
+   value/type
+2. Add an `$ExpectType` test for the new API to ensure it has the correct type.
+
+To remove an API:
+
+1. Remove it from any `hasExactKeys` statements
+2. Remove any `$ExpectType` tests related to it
+
+#### Symbols
+
+Symbols are often used for internal state that is only accessible within a
+framework. We use a few symbols internally in these packages, and because of
+this they appear in the public type signatures, and assertions. However, unless
+the symbol itself is part of the public JS API of the package, these properties
+are _inacessible_ to users, and thus they are not part of public API, and any
+changes can be made and released in a patch release.

test/types/component-test.ts

@@ -40,7 +40,9 @@ hasExactKeys<{
   isDestroyed: unknown,
   willDestroy: unknown,
 
-  // These are not public API, but technically part of the shape
+  // These are not public API, but technically exist as keys on the class, so
+  // we have to include them to type check correctly. These can be removed or
+  // changed without a major version bump.
   [DESTROYED]: unknown,
   [DESTROYING]: unknown,
 }>()(component);