From 8a7c70eb95d7727b712acab61e02dbdf3705afde Mon Sep 17 00:00:00 2001 From: Justin Grant Date: Wed, 21 Nov 2018 19:14:37 -0800 Subject: [PATCH 1/4] Updated to clarify versioning behavior Fixed a few things with version-related documentation: * clarified the relationship of typings package version vs. library versions * explained how package versions and library versions can get out of sync * fixed broken links in major-version-upgrade section * clarified major-version-upgrade section See #25677 for more discussion and background for these changes. --- README.md | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9a31d73da1..8663bbb140 100644 --- a/README.md +++ b/README.md @@ -256,14 +256,43 @@ If the standard is still a draft, it belongs here. Use a name beginning with `dom-` and include a link to the standard as the "Project" link in the header. When it graduates draft mode, we may remove it from DefinitelyTyped and deprecate the associated `@types` package. -#### I want to update a package to a new major version +#### How do DefinitelyTyped package versions relate to versions of the corresponding library? -If you intend to continue updating the older version of the package, you may create a new subfolder with the current version e.g. `v2`, and copy existing files to it. If so, you will need to: +_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 is 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 version `10.12`. Because this version is included in the typings file, the NPM version of the `@types/node` package will also be `10.12`: + +```javascript +// Type definitions for Node.js 10.12 +// Project: http://nodejs.org/ +// Definitions by: Microsoft TypeScript +// DefinitelyTyped +// Alberto Schiabel +``` + +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. + +* The patch version of the typings package is incremented every time an updated typings file is published for the same major and minor version. For example, a library may have only published `2.3.0` but the typings package might have gone through several revisions so its version would be `2.3.4`. If the library is later updated to `2.3.6` without any type updates needed, then the typings version would remain `2.3.4`. +* 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.1.3` even as the library goes to `2.2.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'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. + +: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: + +#### If a library is updated to a new major version with breaking changes, how should I update its typings 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. + +Many libraries have a large installed base of developers (including mainatiners of other packages using that library as a dependency) who 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. + +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. + +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. 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 [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, there's 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: ```json { @@ -281,10 +310,9 @@ For example [history v2 `tsconfig.json`](https://github.com/DefinitelyTyped/Defi } ``` -If there are other packages on 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 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/tsconfig.json) has a path mapping to `"history": [ "history/v2" ]`; -transitively `react-router-bootstrap` (which depends on `react-router`) also adds a path mapping in its [tsconfig.json](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-router-bootstrap/tsconfig.json). +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. Also, `/// ` will not work with path mapping, so dependencies must use `import`. From 30c8898e6866fd6820a75998616de91e88fa9207 Mon Sep 17 00:00:00 2001 From: Justin Grant Date: Fri, 23 Nov 2018 18:17:19 -0800 Subject: [PATCH 2/4] Changes in response to @Flarna review --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8663bbb140..aee5a1d07e 100644 --- a/README.md +++ b/README.md @@ -260,7 +260,7 @@ 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 is 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 version `10.12`. Because this version is included in the typings file, the NPM version of the `@types/node` package will also be `10.12`: +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`. ```javascript // Type definitions for Node.js 10.12 @@ -270,11 +270,13 @@ Each DefinitelyTyped package is versioned when published to NPM. The [automated // Alberto Schiabel ``` +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. + 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. -* The patch version of the typings package is incremented every time an updated typings file is published for the same major and minor version. For example, a library may have only published `2.3.0` but the typings package might have gone through several revisions so its version would be `2.3.4`. If the library is later updated to `2.3.6` without any type updates needed, then the typings version would remain `2.3.4`. -* 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.1.3` even as the library goes to `2.2.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. +* 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. :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: @@ -283,7 +285,7 @@ Sometimes typings versions and library versions can get out of sync. Below are a [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. -Many libraries have a large installed base of developers (including mainatiners of other packages using that library as a dependency) who 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 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. 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. @@ -292,7 +294,7 @@ Because the root folder should always contain the typings for the latest ("new") 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, there's 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 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: ```json { From 60a7ec20eebfbe1c0c98100a718e1422dfdeb685 Mon Sep 17 00:00:00 2001 From: Justin Grant Date: Tue, 4 Dec 2018 12:26:57 -0800 Subject: [PATCH 3/4] Updated in response to @DanielRosenwasser feedback 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. --- README.md | 47 +++++++++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index aee5a1d07e..650cecd1d5 100644 --- a/README.md +++ b/README.md @@ -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 ``` -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, `/// ` will not work with path mapping, so dependencies must use `import`. From 0f1a0a5d6e20dbab8bbe4ee1eac23e7503908b66 Mon Sep 17 00:00:00 2001 From: Daniel Rosenwasser Date: Wed, 6 Feb 2019 18:38:21 -0800 Subject: [PATCH 4/4] Update README.md --- README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 650cecd1d5..faee7a4ee0 100644 --- a/README.md +++ b/README.md @@ -261,10 +261,10 @@ 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 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`. +The [types-publisher](https://github.com/Microsoft/types-publisher) (the tool that publishes `@types` packages to npm) will set the declaration package's version by using the `major.minor` version number listed in the first line of its `index.d.ts` file. +For example, here are the first few lines of [Node's type declarations](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/node/index.d.ts) for version `10.12.x` at the time of writing: -```javascript +```js // Type definitions for Node.js 10.12 // Project: http://nodejs.org/ // Definitions by: Microsoft TypeScript @@ -272,21 +272,24 @@ For example, below are the first few lines of the latest (as of late 2018) [node // Alberto Schiabel ``` -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`). +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 the `major.minor` version (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 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. +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 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. +* 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 updating a package for new functionality, don't forget to update the version number to line up with that version of the library. + If users make sure versions correspond between JavaScript packages and their respective `@types` packages, then `npm update` should typically just work. +* 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. + If you're impacted by this, you can be the change you want to see in the world and you can be that helpful community member! -: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: +: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 type declaration package? @@ -305,9 +308,8 @@ Because the root folder should always contain the type declarations for the late 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 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: +Because many users still consumed the older `2.x` version, a maintainer who wanted to update the type declarations for this library to `3.x` added a `v2` folder inside the history repository that contains type declarations for the older version. +At the time of writing, the [history v2 `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/history/v2/tsconfig.json) looks roughly like: ```json {