Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork2.8k
docs: describe update steps for ESLint, Node, and TypeScript#6251
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
JoshuaKGoldberg merged 3 commits intotypescript-eslint:mainfromJoshuaKGoldberg:dependant-version-upgradesJan 30, 2023
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
Show all changes
3 commits Select commitHold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
29 changes: 15 additions & 14 deletionsdocs/maintenance/VERSIONING.md → docs/maintenance/Versioning.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,5 @@ | ||
| --- | ||
| id: 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. | ||
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| ### TypeScript | ||
| > The version range of TypeScript currently supported is `>=3.3.1 <5.0.0`. | ||
JoshuaKGoldberg marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| 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: [Parser > `warnOnUnsupportedTypeScriptVersion`](../architecture/Parser.mdx#warnonunsupportedtypescriptversion). | ||
| ## Breaking Changes | ||
121 changes: 121 additions & 0 deletionsdocs/maintenance/versioning/dependant-version-upgrades.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 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). |
2 changes: 1 addition & 1 deletionpackages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
11 changes: 10 additions & 1 deletionpackages/website/sidebars/sidebar.base.js
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.