diff --git a/README.md b/README.md index c76b66a4e..7deec3737 100644 --- a/README.md +++ b/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. diff --git a/test/types/component-test.ts b/test/types/component-test.ts index 71b09f081..81dddd919 100644 --- a/test/types/component-test.ts +++ b/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);