From 39a30fdc4c83fe739862a87a02ebdf7b84b91476 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 18 Dec 2022 15:49:48 -0500 Subject: [PATCH 1/3] docs: describe update steps for ESLint, Node, and TypeScript --- docs/maintenance/VERSIONING.md | 29 +++-- .../versioning/dependant-version-upgrades.mdx | 121 ++++++++++++++++++ packages/website/sidebars/sidebar.base.js | 11 +- 3 files changed, 146 insertions(+), 15 deletions(-) create mode 100644 docs/maintenance/versioning/dependant-version-upgrades.mdx diff --git a/docs/maintenance/VERSIONING.md b/docs/maintenance/VERSIONING.md index 0dd31ae90c1b..d9a4224dbf8a 100644 --- a/docs/maintenance/VERSIONING.md +++ b/docs/maintenance/VERSIONING.md @@ -1,6 +1,5 @@ --- id: versioning -sidebar_label: Versioning title: Versioning --- @@ -28,9 +27,22 @@ During these periods, we manually publish `canary` releases until we are happy w ## Dependant Versions +> See [Versioning > Dependant Version Upgrades](./versioning/dependant-version-upgrades.mdx) for maintenance steps to update these versions. + +### ESLint + +> The version range of ESLint currently supported is `^6.0.0 || ^7.0.0 || ^8.0.0`. + +We generally support at least the latest two major versions of ESLint. + +### Node + +This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://nodejs.org/en/about/releases). +Support for specific Current status releases are considered periodically. + ### TypeScript -> The version range of TypeScript currently supported is `>=3.3.1 <4.9.0`. +> The version range of TypeScript currently supported is `>=3.3.1 <5.0.0`. These versions are what we test against. @@ -42,18 +54,7 @@ Note that our packages have an open `peerDependency` requirement in order to all If you use a non-supported version of TypeScript, the parser will log a warning to the console. If you want to disable this warning, you can configure this in your `parserOptions`. -See: [`@typescript-eslint/parser`](./packages/parser/ TODO JOSH) and [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/ TODO JOSH). - -### ESLint - -> The version range of ESLint currently supported is `^6.0.0 || ^7.0.0 || ^8.0.0`. - -We generally support at least the latest two major versions of ESLint. - -### Node - -This project makes an effort to support Active LTS and Maintenance LTS release statuses of Node according to [Node's release document](https://nodejs.org/en/about/releases). -Support for specific Current status releases are considered periodically. +See: [Parser > `warnOnUnsupportedTypeScriptVersion`](../architecture/Parser.mdx#warnonunsupportedtypescriptversion). ## Breaking Changes diff --git a/docs/maintenance/versioning/dependant-version-upgrades.mdx b/docs/maintenance/versioning/dependant-version-upgrades.mdx new file mode 100644 index 000000000000..972d138791a5 --- /dev/null +++ b/docs/maintenance/versioning/dependant-version-upgrades.mdx @@ -0,0 +1,121 @@ +--- +id: dependant-version-upgrades +title: Dependant Version Upgrades +--- + +## ESLint + +The typescript-eslint repository contains four kinds of version ranges for the `eslint` package: + +- Integration tests: Pinned to our lowest supported ESLint version +- Packages with a `*` `peerDependency` version: These fall back to the explicit `peerDependency` versions +- Packages with explicit `peerDependency` versions: The full range of supported ESLint major versions +- [Root `package.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/package.json)'s' `devDependency`: A relatively recent release, used only for repository development + +:::tip +Whenever you discover any new areas of work that are blocked by dropping an old ESLint version, such as new ESLint API deprecations, add a _TODO_ comment that will be caught by the regular expressions under [Removing Support for an Old ESLint Version](#removing-support-for-an-old-eslint-version). +::: + +### Adding Support for a New ESLint Version + +1. Upgrade the root `package.json` `devDependency` to the latest ESLint +1. Add the new major version to the explicit `peerDependency` versions +1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well. +1. Update [Versioning > ESLint](../Versioning.md#eslint) + +### Removing Support for an Old ESLint Version + +1. Increase the integration tests to the next lowest supported major version (`*.0.0`) +1. Remove the old major versions from packages with explicit `peerDependency` versions +1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of ESLint. + - For example, to remove support for v5, searches might include: + - `/eslint.*5/i` + - `/todo.*eslint.*5/i` + - `/todo.*eslint/i` +1. Update [Versioning > ESLint](../Versioning.md#eslint) + +See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference. + +## Node + +The typescript-eslint repository contains three kinds of version ranges for Node: + +- [`.github/workflows/ci.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml)'s `PRIMARY_NODE_VERSION`: Set to the highest Node version we support +- `node-version`: Set to a tuple of our [lowest, highest] supported versions for our unit tests in CI +- `engines` field in all `package.json`s: explicitly lists all supported Node ranges + +Change those numbers accordingly when adding support for a new Node version or removing support for an old Node version. + +See [feat: drop support for node v12](https://github.com/typescript-eslint/typescript-eslint/pull/5918) + [chore: test node v14 on ci.yml](https://github.com/typescript-eslint/typescript-eslint/pull/5512) for reference. + +## TypeScript + +### Adding Support for a New TypeScript Version + +We generally start the process of supporting a new TypeScript version just after the first beta release for that version is made available. + +1. Create and pin an issue with a title like _TypeScript X.Y Support_, `accepting prs`, `AST`, `dependencies`, and `New TypeScript Version` labels, and the following contents: + + 1. A link to the _TypeScript X.Y Iteration Plan_ issue from the Microsoft issue tracker + 2. The following text: + + ```md + This issue is just to track all of the new features and their implementation state in this project. + As with all releases, we will not necessarily to support all features until closer to the full release when everything the features are stabilised. + + _Please be patient._ + ``` + + 3. A heading starting with `🔲 ` for each new TypeScript feature called out in the iteration plan that will impact us + 4. A heading titled _🔲 `lib.d.ts` Updates_ and the content _We will need to regenerate our types within `scope-manager`_ + 5. A heading titled _Other changes with no impact to us_ containing a list of other changes that we don't believe will impact us + +1. At this stage, it's fine to send and/or review PRs that implement necessary features, but wait to merge them until the new TypeScript version's RC is released + - Whenever a PR is created, add ` (#1234)` to its respective heading, and change the heading's emoji from 🔲 to 🏗 + - Search for `expectBabelToNotSupport` to see how to support syntaxes not yet supported by Babel +1. Once the TypeScript RC version is released, start merging PRs + - Whenever a PR is merged, change the respective heading's emoji from 🏗 to ✅ +1. Create a PR with a title like `feat: update TypeScript to X.Y-rc` and the following changes: + - In the root `package.json`, add `|| X.Y.2-rc2` to the `dependency` on `typescript` + - In the root `package.json`, change the `devDependency` on `typescript` to `~X.Y.2-rc2` + - Change the `SUPPORTED_TYPESCRIPT_VERSIONS` constant's `<` version to the next version of TypeScript + - Change the `SUPPORTED_PRERELEASE_RANGES` constant to equal `['X.Y.2-rc']` + - Rename and update `patches/typescript*` to the new TypeScript version + - Run `yarn generate:lib` to update `scope-manager` +1. Once all PRs needed for the RC update PR are merged, merge the RC update PR +1. Once TypeScript releases the stable X.Y version, create and merge a PR with a title like `chore: bump TypeScript from X.YRC to X.Y` and the following changes: + - In the root `package.json`, remove `|| X.Y.2-rc2` from the `dependency` on `typescript`, and bump its `<` version to the next version of TypeScript + - In the root `package.json`, change the `devDependency` on `typescript` to `~X.Y.3` + - Rename and update `patches/typescript*` to the new TypeScript version + - Any other changes made necessary due to changes in TypeScript between the RC version and stable version + - Update the supported version range in [Versioning](../Versioning.md) +1. Update [Versioning > TypeScript](../Versioning.md#typescript) +1. Send a PR that updates this documentation page to point to your newer issues and PRs + - Also update any of these steps if you go with a different process + +See for reference (caveat: these don't follow the exact process described here): + +- [TypeScript 4.7 Support](https://github.com/typescript-eslint/typescript-eslint/issues/4800) +- [TypeScript 4.8 Support](https://github.com/typescript-eslint/typescript-eslint/issues/5227) +- [feat: support TypeScript 4.8](https://github.com/typescript-eslint/typescript-eslint/pull/5551) +- [feat: support TypeScript 4.9](https://github.com/typescript-eslint/typescript-eslint/pull/5716) +- [chore: bump TS from 4.9RC to 4.9](https://github.com/typescript-eslint/typescript-eslint/commit/a40a311bb52a2b1cfac43851b201f8cfc96c8d5d) + +### Removing Support for an Old TypeScript Version + +A single PR can remove support for old TypeScript versions as a breaking change: + +1. Update the root `package.json` `devDependency` +1. Update the `SUPPORTED_TYPESCRIPT_VERSIONS` constant in `warnAboutTSVersion.ts` +1. Update the `versions` constant in `version-check.ts` +1. Update [Versioning > TypeScript](../Versioning.md#typescript) +1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of TypeScript. + - For example, to remove support for v4.3, searches might include: + - `4.3` + - `/is.*4.*3/i` + - `/semver.*4.*3/i` + - `/semver.satisfies/` + - `/todo.*ts/i` + - `/todo.*typescript/i` + +See [feat: bump minimum supported TS version to 4.2.4](https://github.com/typescript-eslint/typescript-eslint/pull/5915). diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index fe84b9c1ae39..6e873ea4b058 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -80,7 +80,16 @@ module.exports = { }, 'maintenance/pull-requests', 'maintenance/releases', - 'maintenance/versioning', + { + collapsible: false, + items: ['maintenance/versioning/dependant-version-upgrades'], + label: 'Versioning', + link: { + id: 'maintenance/versioning', + type: 'doc', + }, + type: 'category', + }, ], label: 'Maintenance', link: { From e83e01d85ed153391e501581b15eafe1f91cbfec Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 18 Dec 2022 15:56:57 -0500 Subject: [PATCH 2/3] lil typo fix, and a heart --- docs/maintenance/versioning/dependant-version-upgrades.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maintenance/versioning/dependant-version-upgrades.mdx b/docs/maintenance/versioning/dependant-version-upgrades.mdx index 972d138791a5..49ba51ce1e46 100644 --- a/docs/maintenance/versioning/dependant-version-upgrades.mdx +++ b/docs/maintenance/versioning/dependant-version-upgrades.mdx @@ -61,9 +61,9 @@ We generally start the process of supporting a new TypeScript version just after ```md This issue is just to track all of the new features and their implementation state in this project. - As with all releases, we will not necessarily to support all features until closer to the full release when everything the features are stabilised. + As with all releases, we will not necessarily support all features until closer to the full release when everything the features are stabilised. - _Please be patient._ + _Please be patient._ ❤️ ``` 3. A heading starting with `🔲 ` for each new TypeScript feature called out in the iteration plan that will impact us From 66708d737855174ef7fe53c0023c4d78497d2e4f Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 18 Dec 2022 16:05:36 -0500 Subject: [PATCH 3/3] Finalize VERSIONING/Versioning.md rename --- docs/maintenance/{VERSIONING.md => Versioning.md} | 0 .../typescript-estree/src/parseSettings/warnAboutTSVersion.ts | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/maintenance/{VERSIONING.md => Versioning.md} (100%) diff --git a/docs/maintenance/VERSIONING.md b/docs/maintenance/Versioning.md similarity index 100% rename from docs/maintenance/VERSIONING.md rename to docs/maintenance/Versioning.md diff --git a/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts b/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts index 191ac029325a..13eef19e7964 100644 --- a/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts +++ b/packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts @@ -3,7 +3,7 @@ import * as ts from 'typescript'; import type { ParseSettings } from './index'; /** - * This needs to be kept in sync with /docs/maintenance/VERSIONING.md + * This needs to be kept in sync with /docs/maintenance/Versioning.md * in the typescript-eslint monorepo */ const SUPPORTED_TYPESCRIPT_VERSIONS = '>=3.3.1 <5.0.0';