vhad/DefinitelyTyped
1
0
Fork 0
mirror of https://github.com/gosticks/DefinitelyTyped.git synced 2026-07-08 11:10:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated in response to @DanielRosenwasser feedback

Browse Source 
Thanks @DanielRosenwasser for feedback! Here's what's different: 
* Updated typos: contaiin,  udpated, udpate, mainatiners
* One sentence per line, except bullet points where adding a newline will show up in user-visible text (GitHub markdown doesn't ignore line breaks in bullet points)
* Removed "typings", replaced with either "type definition(s)" or "type definition package" depending on context

Happy to make more edits, just let me know.
This commit is contained in:
Justin Grant
2018-12-04 12:26:57 -08:00
committed by GitHub
parent 30c8898e68
commit 60a7ec20ee
1 changed files with 31 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

@@ -260,7 +260,9 @@ When it graduates draft mode, we may remove it from DefinitelyTyped and deprecat
_NOTE: The discussion in this section assumes familiarity with [Semantic versioning](https://semver.org/)_
Each DefinitelyTyped package is versioned when published to NPM. The [automated tools](https://github.com/Microsoft/types-publisher) that publish typings packages to NPM will set the typings package's version using the version number listed in the first line of the typings file. For example, below are the first few lines of the latest (as of late 2018) [node.js typings file](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/index.d.ts) for node.js library versions `10.12.x`.
Each DefinitelyTyped package is versioned when published to NPM.
The [automated tools](https://github.com/Microsoft/types-publisher) that publish type declaration packages to NPM will set the type declaration package's version using the version number listed in the first line of its `index.d.ts` file.
For example, below are the first few lines of the latest (as of late 2018) [node.js type declarations](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/index.d.ts) for node.js library versions `10.12.x`.
```javascript
// Type definitions for Node.js 10.12
@@ -270,31 +272,42 @@ Each DefinitelyTyped package is versioned when published to NPM. The [automated
// Alberto Schiabel <https://github.com/jkomyno>
```
Because `10.12` is at the end the first line, the NPM version of the `@types/node` package will also be `10.12.x`. Note that the first-line comment in the typings file should only contaiin major/minor versions (e.g. `10.12`) and should not contain a patch version (e.g. `10.12.4`). This is because only the major and minor release numbers are aligned between library packages and typings packages. The patch release number of the typings package (e.g. `.0` in `10.12.0`) is initialized to zero by DefinitelyTyped and is incremented each time a new `@types/node` package is published to NPM for the same major/minor version of the corresponding library.
Because `10.12` is at the end the first line, the NPM version of the `@types/node` package will also be `10.12.x`.
Note that the first-line comment in the `index.d.ts` file should only contain major/minor versions (e.g. `10.12`) and should not contain a patch version (e.g. `10.12.4`).
This is because only the major and minor release numbers are aligned between library packages and type declaration packages.
The patch release number of the type declaration package (e.g. `.0` in `10.12.0`) is initialized to zero by DefinitelyTyped and is incremented each time a new `@types/node` package is published to NPM for the same major/minor version of the corresponding library.
Sometimes typings versions and library versions can get out of sync. Below are a few common reasons why, in order of how much they inconvenience users of a library. Only the last case is typically problematic.
Sometimes type declaration package versions and library package versions can get out of sync.
Below are a few common reasons why, in order of how much they inconvenience users of a library.
Only the last case is typically problematic.
* As noted above, the patch version of the typings package is unrelated to the library patch version. This allows DefinitelyTyped to safely update typings for the same major/minor version of a library.
* If a minor release adds new features that don't impact the type system, then there's no need to publish an updated typings file. In cases like this, updates are often skipped to the typings file. For example, imagine a contrived example of a library that formats only integers in its `2.0` release. If a `2.1` release of the library adds the capability to format floating point numbers too without changing API type signatures, then the typings version might remain `2.0.3` even as the library goes to `2.1.0`.
* Users who are updating typings for a library sometimes forget to increment the typings version to match the library version. This doesn't usually result in any problems because `npm update` will usually pick the latest typings version, although it may be confusing for users because they might assume that a library update is missing types that are really present. It will also cause problems when libraries are (see below) updated to a new major release with breaking changes, because users won't know which typings version is the right one to use for older versions of the library.
* It's common for typings to lag behind library updates because it's often library users, not maintainers, who update DefinitelyTyped when new library features are released. So there may be a lag of days, weeks, or even months before a helpful community member sends a PR to update the typings for a new library release.
* As noted above, the patch version of the type declaration package is unrelated to the library patch version. This allows DefinitelyTyped to safely update type declarations for the same major/minor version of a library.
* If a minor release adds new features that don't impact the type system, then there's no need to publish updated type declarations. In cases like this, updates are often skipped to the type declaration package. For example, imagine a contrived example of a library that formats only integers in its `2.0` release. If a `2.1` release of the library adds the capability to format floating point numbers too without changing API type signatures, then the type declaration package version might remain `2.0.3` even as the library goes to `2.1.0`.
* Users who are updating type declarations for a library sometimes forget to increment the type declaration package's version to match the library version. This doesn't usually result in any problems because `npm update` will usually pick the latest type declaration package version, although it may be confusing for users because they might assume that a library update is missing types that are really present. It will also cause problems when libraries are (see below) updated to a new major release with breaking changes, because users won't know which type declaration package version is the right one to use for older versions of the library.
* It's common for type declaration package updates to lag behind library updates because it's often library users, not maintainers, who update DefinitelyTyped when new library features are released. So there may be a lag of days, weeks, or even months before a helpful community member sends a PR to update the type declaration package for a new library release.
:exclamation:If you're updating the typings for a library version, always set the major/minor version in the first line of the typings file to match the library version that you're documenting!:exclamation:
:exclamation:If you're updating type declarations for a library, always set the major/minor version in the first line of `index.d.ts` to match the library version that you're documenting!:exclamation:
#### If a library is updated to a new major version with breaking changes, how should I update its typings package?
#### If a library is updated to a new major version with breaking changes, how should I update its type declaration package?
[Semantic versioning](https://semver.org/) requires that versions with breaking changes must increment the major version number. For example, a library that removes a publicly exported function after its `3.5.8` release must bump its version to `4.0.0` in its next release. Furthermore, when the library's `4.0.0` release is out, its DefinitelyTyped typings should also be updated to `4.0.0`, including any breaking changes to the library's API.
[Semantic versioning](https://semver.org/) requires that versions with breaking changes must increment the major version number.
For example, a library that removes a publicly exported function after its `3.5.8` release must bump its version to `4.0.0` in its next release.
Furthermore, when the library's `4.0.0` release is out, its DefinitelyTyped type declaration package should also be updated to `4.0.0`, including any breaking changes to the library's API.
Many libraries have a large installed base of developers (including mainatiners of other packages using that library as a dependency) who won't move right away to a new version that has breaking changes, because it might be months until a maintainer has time to rewrite code to adapt to the new version. In the meantime, users of old library versions still may want to udpate typings for older versions.
Many libraries have a large installed base of developers (including maintainers of other packages using that library as a dependency) who won't move right away to a new version that has breaking changes, because it might be months until a maintainer has time to rewrite code to adapt to the new version.
In the meantime, users of old library versions still may want to update type declarations for older versions.
If you intend to continue updating the older version of the typings package, you may create a new subfolder (e.g. `/v2/`) named for the current (soon to be "old") version, and copy existing files from the current version to it.
If you intend to continue updating the older version of a library's type declarations, you may create a new subfolder (e.g. `/v2/`) named for the current (soon to be "old") version, and copy existing files from the current version to it.
Because the root folder should always contain the typings for the latest ("new") version, you'll need to make a few changes to the files in your old-version subdirectory to ensure that relative path references point to the subdirectory, not the root.
Because the root folder should always contain the type declarations for the latest ("new") version, you'll need to make a few changes to the files in your old-version subdirectory to ensure that relative path references point to the subdirectory, not the root.
1. Update the relative paths in `tsconfig.json` as well as `tslint.json`.
2. Add path mapping rules to ensure that tests are running against the intended version.
For example, the [`history`](https://github.com/ReactTraining/history/) library introduced breaking changes between version `2.x` and `3.x`. Many developers waited a while to update their `package.json` to depend on version `3.x` of `history`. Therefore, a maintainer of the typings for this library added a `v2` folder inside the history repository that contains typings for the older version. The [history v2 `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/history/v2/tsconfig.json) looks like:
For example, the [`history`](https://github.com/ReactTraining/history/) library introduced breaking changes between version `2.x` and `3.x`.
Many developers waited a while to update their `package.json` to depend on version `3.x` of `history`.
Therefore, a maintainer of the type declarations for this library added a `v2` folder inside the history repository that contains type declarations for the older version.
The [history v2 `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/history/v2/tsconfig.json) looks like:
```json
{
@@ -312,9 +325,11 @@ For example, the [`history`](https://github.com/ReactTraining/history/) library
}
```
If there are other packages in DefinitelyTyped that are incompatible with the new version, you will need to add path mappings to the old version. You will also need to do this recursively for packages depending on packages depending on the old version.
If there are other packages in DefinitelyTyped that are incompatible with the new version, you will need to add path mappings to the old version.
You will also need to do this recursively for packages depending on packages depending on the old version.
For example, `react-router` depends on `history@2`, so [react-router `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-router/v2/tsconfig.json) has a path mapping to `"history": [ "history/v2" ]`. Transitively, `react-router-bootstrap` (which depends on `react-router`) also needed to add the same path mapping (`"history": [ "history/v2" ]`) in its `tsconfig.json` until its `react-router` dependency was udpated to the latest version.
For example, `react-router` depends on `history@2`, so [react-router `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-router/v2/tsconfig.json) has a path mapping to `"history": [ "history/v2" ]`.
Transitively, `react-router-bootstrap` (which depends on `react-router`) also needed to add the same path mapping (`"history": [ "history/v2" ]`) in its `tsconfig.json` until its `react-router` dependency was updated to the latest version.
Also, `/// <reference types=".." />` will not work with path mapping, so dependencies must use `import`.