From 658ccfec21d5d01408947f1f855ba060240f93e5 Mon Sep 17 00:00:00 2001 From: Brad Zacher Date: Mon, 27 Jun 2022 00:33:20 -0700 Subject: [PATCH 01/11] docs: add maintainer guide --- .cspell.json | 1 + docs/contributor/MANAGING_ISSUES.md | 56 +++++++++ docs/contributor/VERSIONING_AND_RELEASES.md | 129 ++++++++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 docs/contributor/MANAGING_ISSUES.md create mode 100644 docs/contributor/VERSIONING_AND_RELEASES.md diff --git a/.cspell.json b/.cspell.json index 0c5b1d6c2866..1161e204e660 100644 --- a/.cspell.json +++ b/.cspell.json @@ -105,6 +105,7 @@ "transpiled", "transpiles", "transpiling", + "triaging", "tsconfigs", "tsutils", "tsvfs", diff --git a/docs/contributor/MANAGING_ISSUES.md b/docs/contributor/MANAGING_ISSUES.md new file mode 100644 index 000000000000..36ec985e6b70 --- /dev/null +++ b/docs/contributor/MANAGING_ISSUES.md @@ -0,0 +1,56 @@ +--- +id: managing-issues +sidebar_label: Managing Issues +title: Managing Issues +--- + +Please note that this document serves as a guide for how you might manage issues. As you become more familiar with the codebase and how it's supposed to behave you'll be able to skip steps or do things out of order as you see fit. For example you may be able to identify if a bug report is "working as intended" or you might recognize an issue as a duplicate without having a completely filled out issue. In such cases you can forgo the back-and-forth and just skip to the closing steps. + +Use your best judgement when triaging issues, but most of all remember to be kind, friendly, and encouraging when responding to users. + +## Bug Reports + +### Ensuring the Issue is Complete + +#### "Simple" bug + +A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a tsconfig) - i.e. an issue reproducible in our web playground. The vast, vast majority of bug reports will fall into this category. + +Before you being reviewing a simple bug report you should first ensure that there is a complete, isolated reproduction case provided by the reporter. This means that there should be a playground link which shows the issue being reported. Whilst a playground link is definitely preferred; it is not explicitly required if there is code and config in the issue that can be pasted into the playground to reproduce the issue. If you cannot reproduce the issue in the playground, remove the "triage" tag, add the "awaiting response" tag, and ask the user to create an isolated reproduction in the playground and comment back when they have one. For example: + +> Thanks for the report `@reporter`. Unfortunately I couldn't reproduce the issue using the code you provided. Could you please create an isolated reproduction in our playground (https://typescript-eslint.io/play/) and comment back when you've got one? We prefer an isolated reproduction so that we as volunteer maintainers can quickly reproduce the issue and more easily find the cause. + +#### "Complex" bug + +A complex bug is a bug that requires multiple files to reproduce. This is the rarer case, but does happen when people are using library types or if there are issues when types are imported. + +Before you being reviewing a complex bug report you should first ensure that there is a link to a github repo that can be checked out to reproduce the issue. Unlike with simple issues - it is not acceptable for these sorts of issues to be missing their link; the reason being that if you're trying to reproduce a case by pasting contents into files it's very, very easy to do something wrong or different to the way the reporter intended - meaning you won't be able to reproduce the issue. This in turn can mean you burn a lot of time trying to get things right. Instead remove the "triage" tag, add the "awaiting response" tag, and ask the user to create an isolated reproduction repo and comment back when they have one. For example: + +> Thanks for the report `@reporter`. Could you please create an isolated reproduction repo for us? Ideally we want a repo that we can just checkout, install, and immediately reproduce the issue so that we as volunteer maintainers can quickly reproduce the issue and more easily find the cause. + +### Triaging the Issue + +#### Looking for Duplicates + +It's usually worth doing a quick search for related issues. Most of the time users are good about this and they won't ever raise an issue to begin with, but there are some people that will raise a duplicate issue for various reasons. If you find an existing issue which matches, you needn't spend any more time on the issue. Remove the "triage" and "bug" tags, add the "duplicate" tag, and close the issue with a comment referencing the duplicate issue. For example: + +> Duplicate of `#12345`. Please make sure you use the search before raising an issue. + +It's worth noting that occasionally a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. If this is the case then you should read the original issue to gather context and understand the reason for it being closed, and determine if the new issue is raises any new or relevant issue that requires addressing. In that case you should continue on the normal triaging flow below. + +#### Bug or Working as Intended? + +Once you're sure the issue is complete and correct, the next step is to determine if the report is "valid" or not. In short we need to determine if the report is the user misunderstanding how code is designed work ("working as intended") or if the report is an actual bug. As you become more familiar with the codebase and how everything works this will be easier to do intuitively, but to begin with this will likely involve investigating the documentation, code, and the tests to determine if it's a bug or working as intended. In general if there is a passing test or documented example that is the same as or similar to the repro code - that indicates that it's working as intended. If you can't find anything that matches, use your best judgement based on the spirit of the code. If you're ever unsure - don't hesitate to loop in a maintainer that has more context to help! + +- If you determine that the bug is due to the user doing something wrong like they've have used the incorrect config, then remove the "bug" and "triage" tags, and add the "working as intended" and "fix: user error" tags, then close the issue with a comment explaining how the user might correct their mistake. [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed). +- If you determine that the bug is working as intended, remove the "bug" and "triage" tags, and add the "working as intended" tag, then close the issue with a comment explaining why the report is working as intended. You needn't go into too much detail in your comment - just enough to explain it. [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+is%3Aclosed). +- If you determine that the bug is actually a bug, remove the "triage" tag, and add the "accepting PRs" tag. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix. If you think that the fix is relatively straight-forward then consider also tagging the issue with "good first issue". + +:::note +If your link is both a "permalink" (includes a commit hash instead of a branch name) and has a line number/line range then GitHub will embed the code in your comment. +When viewing a file in GitHub pressing `y` will update the URL to a "permalink" with the current commit hash, then you can select the relevant lines and paste that URL into the comment. +::: + +## New Rules + +## Rule Enhancements diff --git a/docs/contributor/VERSIONING_AND_RELEASES.md b/docs/contributor/VERSIONING_AND_RELEASES.md new file mode 100644 index 000000000000..f31ce46322d2 --- /dev/null +++ b/docs/contributor/VERSIONING_AND_RELEASES.md @@ -0,0 +1,129 @@ +--- +id: versioning-and-releases +sidebar_label: Versioning and Releases +title: Versioning and Releases +--- + +## Releases + +### Canary + +We release a canary version for each and every commit to `main` that passes all required checks. This release is performed automatically by the [`publish_canary_version` step](https://github.com/typescript-eslint/typescript-eslint/blob/5feb2dba9da2bd5e233451b7b0f1c99414b5aef9/.github/workflows/ci.yml#L234-L263). + +This release is goes to the `canary` tag on npm and it is versioned as an incremental canary patch release on top of the current `latest` version. I.e. if the current version is `5.6.1`, then the first canary version will be `5.6.2-alpha.0`, the second `5.6.2-alpha.1`, and so on. + +### Latest + +We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by an external job (TBA migration to GitHub actions). This release goes to the standard `latest` tag on npm. + +See the [versioning](#versioning) section below for how the version number is calculated. + +If there have been no commits that impact public-facing packages then a patch-level release shall be released. + +Latest releases shall only ever be "minor" or "patch" releases. + +### Major Releases + +We currently do not have a set schedule around when major releases shall be performed; instead they shall be done as the need arises. We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`. +When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch. + +
+ +This section details the steps for a major release. + +1. Create a new branch off `main` called `v${major}`. This branch should be created in the project repository (not your personal fork). +1. Add a new step to [the CI workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml). This step should be exactly the same as the `publish_canary_version` step except: + 1. The publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`. + 1. The step should have the condition: `if: github.ref == 'refs/heads/v${major}'`. +1. Raise a new PR merging the new branch into `main`. + - This PR serves as documentation of the changes as well as a place for directed feedback. +1. Any breaking change PRs should have their target branch switched to this branch. + - To signify these changes as breaking changes, the first line of the PR description must read as `BREAKING CHANGE:`. + - It is important to note that when merged the commit message must also include `BREAKING CHANGE:` as the first line in order for lerna to recognize it as a breaking change in the release notes. If you miss this it just means more manual work when writing the release documentation. +1. Non-breaking changes can be merged to `main` or the major branch as desired. They do not need any special treatment. +1. Once all required PRs have been merged - let the release bake for at least 1 week to allow time for early adopters to help test it. + - Consider promoting it on the [`@tseslint`](https://twitter.com/tseslint) twitter to get some additional attention. +1. Once the RC has baked for long enough, rebase merge the PR on top of `main`. +1. Discuss with the maintainers to organize an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. +1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. +1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! + +
+ +### Out-of-Band + +Rarely we will do releases "out-of-band" (outside the [latest](#latest) schedule). These releases are done manually by a maintainer with the required access privileges. + +These releases are done only in emergencies. We assess need on a case-by-case basis though generally an emergency is defined as a critical regression specifically introduced in the latest release. + +### Back-Porting Releases + +We **_do not_** back port releases to previously released major/minor versions; we only ever release forward. + +## Versioning + +In this project we follow [semantic versioning (semver)](https://semver.org/). This page exists to help set guidelines around when what we consider to fall within each of the semver categories. + +All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations. + +When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have _very_ different API surfaces, they also are consumed in very different ways. + +Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes. + +### Internal packages + +Any packages in this project that are not part of our public API surface (such as `eslint-plugin-internal` or `website`) shall not be considered when calculating new package versions. + +### `ast-spec` and `visitor-keys` + +A change to the AST **_shall_** be considered breaking if it: + +- Removes or renames an existing AST Node. +- Removes or renames an existing property on an AST Node. +- Changes a type in a non-refining way (i.e. `string` to `number`). + +A change to the AST **_shall not_** be considered breaking if it: + +- Adds a new property to the AST. +- Adds a new node type to the AST. +- Adds a new node type to an existing union type. +- Refines a type to be more specific (i.e. `string` to `'literal' | 'union'`). +- Removes a type from a union that was erroneously added and did not match the runtime AST. + +### `eslint-plugin` and `eslint-plugin-tslint` + +A change to the plugins **_shall_** be considered breaking if it: + +- Removes or renames an option. +- Changes the default option of a rule. +- Changes a rule's schema to be stricter. +- Consumes type information to a rule that did not previously consume it. +- Removes or renames a rule. +- Changes any of the recommended configurations. +- Changes the default behavior of a rule in such a way that causes new reports in a large set of cases in an average codebase. + +A change to the plugins **_shall not_** be considered breaking if it: + +- Adds an option. +- Adds a rule. +- Deprecates a rule. +- Adds additional checks to an existing rule that causes new reports in a small-to-medium set of cases in an average codebase. +- Refactors a rule's code in a way that does not introduce additional reports. +- Changes to a rule's description or other metadata. +- Adds a fixer or suggestion fixer. +- Removes a fixer or suggestion fixer. +- Fixes incorrect behavior in a rule that may or may not introduce additional reports. + +#### `parser`, `typescript-estree`, `scope-manager`, `types`, `type-utils`, `utils` + +A change to these packages **_shall_** be considered breaking if it: + +- Changes the API surface in a backwards-incompatible way (remove or rename functions, types, etc). + +A change to these packages **_shall not_** be considered breaking if it: + +- Adds to the API surface (add functions, types, etc). +- Deprecates parts of the API surface. +- Adds **_optional_** arguments to functions or properties to input types. +- Adds additional properties to output types. +- Adds documentation in the form of JSDoc comments. From 4213238d22688815724099eee99cb0faa42533d8 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 24 Oct 2022 17:20:00 -0400 Subject: [PATCH 02/11] Went over docs again --- docs/contributor/MANAGING_ISSUES.md | 56 ---------- docs/maintenance/ISSUES.md | 101 ++++++++++++++++++ .../VERSIONING_AND_RELEASES.md | 2 +- packages/website/sidebars/sidebar.base.js | 17 ++- 4 files changed, 117 insertions(+), 59 deletions(-) delete mode 100644 docs/contributor/MANAGING_ISSUES.md create mode 100644 docs/maintenance/ISSUES.md rename docs/{contributor => maintenance}/VERSIONING_AND_RELEASES.md (99%) diff --git a/docs/contributor/MANAGING_ISSUES.md b/docs/contributor/MANAGING_ISSUES.md deleted file mode 100644 index 36ec985e6b70..000000000000 --- a/docs/contributor/MANAGING_ISSUES.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: managing-issues -sidebar_label: Managing Issues -title: Managing Issues ---- - -Please note that this document serves as a guide for how you might manage issues. As you become more familiar with the codebase and how it's supposed to behave you'll be able to skip steps or do things out of order as you see fit. For example you may be able to identify if a bug report is "working as intended" or you might recognize an issue as a duplicate without having a completely filled out issue. In such cases you can forgo the back-and-forth and just skip to the closing steps. - -Use your best judgement when triaging issues, but most of all remember to be kind, friendly, and encouraging when responding to users. - -## Bug Reports - -### Ensuring the Issue is Complete - -#### "Simple" bug - -A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a tsconfig) - i.e. an issue reproducible in our web playground. The vast, vast majority of bug reports will fall into this category. - -Before you being reviewing a simple bug report you should first ensure that there is a complete, isolated reproduction case provided by the reporter. This means that there should be a playground link which shows the issue being reported. Whilst a playground link is definitely preferred; it is not explicitly required if there is code and config in the issue that can be pasted into the playground to reproduce the issue. If you cannot reproduce the issue in the playground, remove the "triage" tag, add the "awaiting response" tag, and ask the user to create an isolated reproduction in the playground and comment back when they have one. For example: - -> Thanks for the report `@reporter`. Unfortunately I couldn't reproduce the issue using the code you provided. Could you please create an isolated reproduction in our playground (https://typescript-eslint.io/play/) and comment back when you've got one? We prefer an isolated reproduction so that we as volunteer maintainers can quickly reproduce the issue and more easily find the cause. - -#### "Complex" bug - -A complex bug is a bug that requires multiple files to reproduce. This is the rarer case, but does happen when people are using library types or if there are issues when types are imported. - -Before you being reviewing a complex bug report you should first ensure that there is a link to a github repo that can be checked out to reproduce the issue. Unlike with simple issues - it is not acceptable for these sorts of issues to be missing their link; the reason being that if you're trying to reproduce a case by pasting contents into files it's very, very easy to do something wrong or different to the way the reporter intended - meaning you won't be able to reproduce the issue. This in turn can mean you burn a lot of time trying to get things right. Instead remove the "triage" tag, add the "awaiting response" tag, and ask the user to create an isolated reproduction repo and comment back when they have one. For example: - -> Thanks for the report `@reporter`. Could you please create an isolated reproduction repo for us? Ideally we want a repo that we can just checkout, install, and immediately reproduce the issue so that we as volunteer maintainers can quickly reproduce the issue and more easily find the cause. - -### Triaging the Issue - -#### Looking for Duplicates - -It's usually worth doing a quick search for related issues. Most of the time users are good about this and they won't ever raise an issue to begin with, but there are some people that will raise a duplicate issue for various reasons. If you find an existing issue which matches, you needn't spend any more time on the issue. Remove the "triage" and "bug" tags, add the "duplicate" tag, and close the issue with a comment referencing the duplicate issue. For example: - -> Duplicate of `#12345`. Please make sure you use the search before raising an issue. - -It's worth noting that occasionally a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. If this is the case then you should read the original issue to gather context and understand the reason for it being closed, and determine if the new issue is raises any new or relevant issue that requires addressing. In that case you should continue on the normal triaging flow below. - -#### Bug or Working as Intended? - -Once you're sure the issue is complete and correct, the next step is to determine if the report is "valid" or not. In short we need to determine if the report is the user misunderstanding how code is designed work ("working as intended") or if the report is an actual bug. As you become more familiar with the codebase and how everything works this will be easier to do intuitively, but to begin with this will likely involve investigating the documentation, code, and the tests to determine if it's a bug or working as intended. In general if there is a passing test or documented example that is the same as or similar to the repro code - that indicates that it's working as intended. If you can't find anything that matches, use your best judgement based on the spirit of the code. If you're ever unsure - don't hesitate to loop in a maintainer that has more context to help! - -- If you determine that the bug is due to the user doing something wrong like they've have used the incorrect config, then remove the "bug" and "triage" tags, and add the "working as intended" and "fix: user error" tags, then close the issue with a comment explaining how the user might correct their mistake. [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed). -- If you determine that the bug is working as intended, remove the "bug" and "triage" tags, and add the "working as intended" tag, then close the issue with a comment explaining why the report is working as intended. You needn't go into too much detail in your comment - just enough to explain it. [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+is%3Aclosed). -- If you determine that the bug is actually a bug, remove the "triage" tag, and add the "accepting PRs" tag. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix. If you think that the fix is relatively straight-forward then consider also tagging the issue with "good first issue". - -:::note -If your link is both a "permalink" (includes a commit hash instead of a branch name) and has a line number/line range then GitHub will embed the code in your comment. -When viewing a file in GitHub pressing `y` will update the URL to a "permalink" with the current commit hash, then you can select the relevant lines and paste that URL into the comment. -::: - -## New Rules - -## Rule Enhancements diff --git a/docs/maintenance/ISSUES.md b/docs/maintenance/ISSUES.md new file mode 100644 index 000000000000..e73b5b1e5a2e --- /dev/null +++ b/docs/maintenance/ISSUES.md @@ -0,0 +1,101 @@ +--- +id: issues +sidebar_label: Issue Management +title: Issue Management +--- + +This document serves as a guide for how you might manage issues, also known as issue triaging. + +Use your best judgement when triaging issues, but most of all remember to be **kind, friendly, and encouraging** when responding to users. + +:::tip +If you're ever unsure on any part of issue management, don't hesitate to loop in a maintainer that has more context to help! +::: + +## Issue Flow + +[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are given the `triage` label. +Most issues go through the following triage flow when created: + +1. Some user files the issue, and it is given the `triage` label automatically +2. A maintainer will ensure the issue is valid: + - If it doesn't fill out an appropriate template with enough information: + - Add the `please fill out the template` and `awaiting response` labels + - Ask the poster for more information using a _Needs More Info_ response + - If it's a duplicate of an issue that already exists: + - Add the `duplicate` label and remove the `bug` label + - If it's an obvious duplicate, post a _Clearly Duplicate Issue_ response + - If it's not an obvious duplicate, link to the existing issue and explain why + - If the code is working as intended: + - Add the `working as intended` label and remove the `bug` and `triage` labels + - If the behavior is due to the user doing something wrong, such as an incorrect config: + - Add the `fix: user error` label + - [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed) + - If the behavior is otherwise expected, [this issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+-label%3A%22fix%3A+user+error%22+is%3Aclosed+) + - You needn't go into too much detail in your comment - just enough to explain it +3. If it was valid, add the `accepting prs` label and remove the `triage` label +4. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix +5. If you think that the fix is relatively straightforward then consider also adding the `good first issue` label + +Whenever an issue is waiting for the reporter to provide more information, it should be given the `awaiting response` label. +When more information is provided: + +- If you have time to go through the triage flow again, do so +- If you don't have time, add the `triage` label and remove the `awaiting response` label + +:::tip +If your link is both a "permalink" (includes a commit hash instead of a branch name) and has a line number/line range then GitHub will embed the code in your comment. +When viewing a file in GitHub pressing `y` will update the URL to a "permalink" with the current commit hash, then you can select the relevant lines and paste that URL into the comment. +::: + +### Determining Whether Code is Working As Intended + +As you become more familiar with the codebase and how everything works this will be easier to do intuitively, but to begin with this will likely involve investigating the documentation, code, and the tests to determine if it's a bug or working as intended. +In general if there is a passing test or documented example that is the same as or similar to the repro code - that indicates that it's working as intended. +If you can't find anything that matches, use your best judgement based on the spirit of the code. + +### Looking for Duplicates + +It's worth noting that occasionally a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. +If this is the case then you should read the original issue to gather context and understand the reason for it being closed, and determine if the new issue is raises any new or relevant issue that requires addressing. + +### Response Templates + +We include a set of common responses to issues in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. +Don't treat these as exact responses you must use: they're just a starting copy+paste helper. +Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues. + +## Skipping Steps + +As you become more familiar with the codebase and how it's supposed to behave you'll be able to skip steps or do things out of order as you see fit. +For example you may be able to identify if a bug report is "working as intended" or you might recognize an issue as a duplicate without having a completely filled out issue. +In such cases you can forgo the back-and-forth and just skip to the closing steps. + +## Specific Issue Types + +### 🐛 Bug Reports + +#### 🐞 "Simple" Bugs + +A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a TSConfig) - i.e. an issue reproducible on https://typescript-eslint.io/play. +The vast majority of bug reports fall into this category. + +If you cannot reproduce the issue as described using the issue's provided playground reproduction, it has not provided enough information. +Consider using a specific response like the _Needs Playground Reproduction_ response. + +#### 🦟 "Complex" Bugs + +A complex bug is a bug that requires multiple files to reproduce. +This is the rarer case, but does happen when people are using library types or if there are issues when types are imported. + +These bugs should be reported with a link to a GitHub repository that can be checked out to reproduce the issue. +If you cannot reproduce the issue as described using repository's README.md and issue description, it has not provided enough information. +Consider using a specific response like the _Needs Full Reproduction_ response. + +### ✨ Rule Enhancements + +TODO: This will be filled out... soon! + +### 🚀 New Rules + +TODO: This will be filled out... soon! diff --git a/docs/contributor/VERSIONING_AND_RELEASES.md b/docs/maintenance/VERSIONING_AND_RELEASES.md similarity index 99% rename from docs/contributor/VERSIONING_AND_RELEASES.md rename to docs/maintenance/VERSIONING_AND_RELEASES.md index f31ce46322d2..a567d0efdbc7 100644 --- a/docs/contributor/VERSIONING_AND_RELEASES.md +++ b/docs/maintenance/VERSIONING_AND_RELEASES.md @@ -48,7 +48,7 @@ When we do do a major release, we release a release candidate version to the `rc 1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. 1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! -
+
### Out-of-Band diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 5b16af7f5f91..3d5b029d2f84 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -1,11 +1,12 @@ module.exports = { docs: [ { - collapsed: false, + collapsible: false, items: [ { label: 'Linting with Type Information', items: ['linting/typed-linting/monorepos'], + collapsible: false, link: { id: 'linting/typed-linting', type: 'doc', @@ -19,6 +20,7 @@ module.exports = { id: 'linting/troubleshooting', type: 'doc', }, + collapsible: false, type: 'category', items: [ 'linting/troubleshooting/formatting', @@ -36,11 +38,12 @@ module.exports = { { type: 'category', label: 'Development', - collapsed: false, + collapsible: false, items: [ { label: 'Architecture', type: 'category', + collapsible: false, items: [ 'development/architecture/asts', 'development/architecture/packages', @@ -49,5 +52,15 @@ module.exports = { 'development/custom-rules', ], }, + { + collapsible: false, + items: ['maintenance/issues', 'maintenance/versioning-and-releases'], + label: 'Maintenance', + link: { + id: 'maintenance', + type: 'doc', + }, + type: 'category', + }, ], }; From f123693602b2110ea9041062ba2b119d7e86dbb1 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 24 Oct 2022 17:23:04 -0400 Subject: [PATCH 03/11] Also updated .github/replies.yml --- .github/replies.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/replies.yml b/.github/replies.yml index 0522dfc445c9..64f02ca54ed8 100644 --- a/.github/replies.yml +++ b/.github/replies.yml @@ -17,6 +17,25 @@ replies: \ If you need it sooner, please try the `canary` tag on NPM. name: Fix Has Been Merged + - body: | + Thanks for the report @!\ + This might be a valid issue, but we can't tell because you haven't filled in enough information.\ + Please fill in the rest of the issue template so we can take a look.\ + Thanks! + name: Needs More Info + - body: | + Thanks for the report @!\ + I can't reproduce the issue using the repository you provided.\ + Could you please comment with instructions on how to reproduce the issue?\ + Thanks! + name: Needs Full Reproduction + - body: | + Thanks for the report @!\ + I can't reproduce the issue using the code you provided.\ + Could you please create an isolated reproduction in our playground (https://typescript-eslint.io/play) and comment back when you've got one?\ + We prefer an isolated reproduction so that we as volunteer maintainers can quickly reproduce the issue and more easily find the cause.\ + Thanks! + name: Needs Playground Reproduction - body: | With any issue opened in this project — it either has visible progress in the form of an attached PR, or it has no progress.\ \ From dbbc8c61e1f84e0c3b4fa738f594532e1870cd8e Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Mon, 24 Oct 2022 17:31:11 -0400 Subject: [PATCH 04/11] Added docs/MAITENANCE.md too --- docs/MAINTENANCE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/MAINTENANCE.md diff --git a/docs/MAINTENANCE.md b/docs/MAINTENANCE.md new file mode 100644 index 000000000000..75f1030c015d --- /dev/null +++ b/docs/MAINTENANCE.md @@ -0,0 +1,12 @@ +--- +id: maintenance +sidebar_label: Maintenance Guide +title: Maintenance Guide +--- + +This is the maintainers guide to working on typescript-eslint. +It's intended for use by contributors who have been given access to at least triage issues and pull requests. +We keep it in the open for visibility into our processes. + +> If you're reading this as a new maintainer: welcome! +> We're happy to have you! ❤️‍🔥 From e0b543ea05faa4cc318498d96039406828918fe3 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 29 Oct 2022 11:11:59 -0400 Subject: [PATCH 05/11] Apply suggestions from code review Co-authored-by: Joshua Chen --- docs/maintenance/ISSUES.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/maintenance/ISSUES.md b/docs/maintenance/ISSUES.md index e73b5b1e5a2e..c2dfbc7bc2e5 100644 --- a/docs/maintenance/ISSUES.md +++ b/docs/maintenance/ISSUES.md @@ -18,8 +18,8 @@ If you're ever unsure on any part of issue management, don't hesitate to loop in Most issues go through the following triage flow when created: 1. Some user files the issue, and it is given the `triage` label automatically -2. A maintainer will ensure the issue is valid: - - If it doesn't fill out an appropriate template with enough information: +2. A maintainer ensures the issue is valid: + - If the poster didn't fill out an appropriate template with enough information: - Add the `please fill out the template` and `awaiting response` labels - Ask the poster for more information using a _Needs More Info_ response - If it's a duplicate of an issue that already exists: @@ -33,9 +33,9 @@ Most issues go through the following triage flow when created: - [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed) - If the behavior is otherwise expected, [this issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+-label%3A%22fix%3A+user+error%22+is%3Aclosed+) - You needn't go into too much detail in your comment - just enough to explain it -3. If it was valid, add the `accepting prs` label and remove the `triage` label +3. If the report is valid, add the `accepting prs` label and remove the `triage` label 4. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix -5. If you think that the fix is relatively straightforward then consider also adding the `good first issue` label +5. If you think that the fix is relatively straightforward, consider also adding the `good first issue` label Whenever an issue is waiting for the reporter to provide more information, it should be given the `awaiting response` label. When more information is provided: @@ -50,14 +50,14 @@ When viewing a file in GitHub pressing `y` will update the URL to a "permalink" ### Determining Whether Code is Working As Intended -As you become more familiar with the codebase and how everything works this will be easier to do intuitively, but to begin with this will likely involve investigating the documentation, code, and the tests to determine if it's a bug or working as intended. -In general if there is a passing test or documented example that is the same as or similar to the repro code - that indicates that it's working as intended. +As you become more familiar with the codebase and how everything works, this will be easier to do intuitively, but to begin with, this will likely involve investigating the documentation, code, and tests to determine if it's a bug or working as intended. +In general, if there is a passing test or documented example that is the same as or similar to the repro code — that indicates it's working as intended. If you can't find anything that matches, use your best judgement based on the spirit of the code. ### Looking for Duplicates -It's worth noting that occasionally a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. -If this is the case then you should read the original issue to gather context and understand the reason for it being closed, and determine if the new issue is raises any new or relevant issue that requires addressing. +It's worth noting that, occasionally, a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. +If this is the case, you should read the original issue to gather context, understand the reason for it being closed, and determine if the new issue raises any new or relevant point that requires addressing. ### Response Templates @@ -68,7 +68,7 @@ Please do adopt your specific responses to your personal tone and to match the t ## Skipping Steps As you become more familiar with the codebase and how it's supposed to behave you'll be able to skip steps or do things out of order as you see fit. -For example you may be able to identify if a bug report is "working as intended" or you might recognize an issue as a duplicate without having a completely filled out issue. +For example, you may be able to identify if a bug report is "working as intended", or you might recognize an issue as a duplicate without having a completely filled-out issue. In such cases you can forgo the back-and-forth and just skip to the closing steps. ## Specific Issue Types From 7108a745e116d84e16a3e424cbb76fdcb45a53a3 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 29 Oct 2022 11:23:35 -0400 Subject: [PATCH 06/11] Tweaked issues ordering and intro --- docs/maintenance/ISSUES.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/maintenance/ISSUES.md b/docs/maintenance/ISSUES.md index c2dfbc7bc2e5..55d1cee6e62d 100644 --- a/docs/maintenance/ISSUES.md +++ b/docs/maintenance/ISSUES.md @@ -6,7 +6,9 @@ title: Issue Management This document serves as a guide for how you might manage issues, also known as issue triaging. -Use your best judgement when triaging issues, but most of all remember to be **kind, friendly, and encouraging** when responding to users. +Use your best judgement when triaging issues, and most of all remember to be **kind, friendly, and encouraging** when responding to users. +Many users are new to open source and/or typed linting. +It's imperative we give them a positive, uplifting experience. :::tip If you're ever unsure on any part of issue management, don't hesitate to loop in a maintainer that has more context to help! @@ -14,11 +16,17 @@ If you're ever unsure on any part of issue management, don't hesitate to loop in ## Issue Flow -[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are given the `triage` label. -Most issues go through the following triage flow when created: +:::note +We include a set of common responses to issues in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. +Don't treat these as exact responses you must use: they're just a starting copy+paste helper. +Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues. +::: + +[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable the `triage` label. +That label is added automatically when a new issue is created. +Most issues go through the following review flow when created or updated: -1. Some user files the issue, and it is given the `triage` label automatically -2. A maintainer ensures the issue is valid: +1. A maintainer ensures the issue is valid: - If the poster didn't fill out an appropriate template with enough information: - Add the `please fill out the template` and `awaiting response` labels - Ask the poster for more information using a _Needs More Info_ response @@ -33,9 +41,9 @@ Most issues go through the following triage flow when created: - [This issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22fix%3A+user+error%22+is%3Aclosed) - If the behavior is otherwise expected, [this issue search has some examples of closing comments](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22working+as+intended%22+-label%3A%22fix%3A+user+error%22+is%3Aclosed+) - You needn't go into too much detail in your comment - just enough to explain it -3. If the report is valid, add the `accepting prs` label and remove the `triage` label -4. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix -5. If you think that the fix is relatively straightforward, consider also adding the `good first issue` label +2. If the report is valid, add the `accepting prs` label and remove the `triage` label +3. If you know the rough steps for a fix, consider writing a comment with links to codebase to help someone put together a fix +4. If you think that the fix is relatively straightforward, consider also adding the `good first issue` label Whenever an issue is waiting for the reporter to provide more information, it should be given the `awaiting response` label. When more information is provided: @@ -59,12 +67,6 @@ If you can't find anything that matches, use your best judgement based on the sp It's worth noting that, occasionally, a user will intentionally raise a duplicate issue because they feel the original issue was closed when it shouldn't have been. If this is the case, you should read the original issue to gather context, understand the reason for it being closed, and determine if the new issue raises any new or relevant point that requires addressing. -### Response Templates - -We include a set of common responses to issues in [`.github/replies.yml`](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/replies.yml), intended to be used with the [Refined Saved Replies](https://github.com/JoshuaKGoldberg/refined-saved-replies) extension. -Don't treat these as exact responses you must use: they're just a starting copy+paste helper. -Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues. - ## Skipping Steps As you become more familiar with the codebase and how it's supposed to behave you'll be able to skip steps or do things out of order as you see fit. From 1d925655e9cb7743affd4fa7084bb0fc6efae041 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 29 Oct 2022 21:23:23 -0400 Subject: [PATCH 07/11] Split up releases and versions; reworked --- docs/development/architecture/PACKAGES.md | 2 +- docs/maintenance/RELEASES.md | 85 +++++++++++++ docs/maintenance/VERSIONING.md | 72 +++++++++++ docs/maintenance/VERSIONING_AND_RELEASES.md | 129 -------------------- packages/website/sidebars/sidebar.base.js | 6 +- 5 files changed, 163 insertions(+), 131 deletions(-) create mode 100644 docs/maintenance/RELEASES.md create mode 100644 docs/maintenance/VERSIONING.md delete mode 100644 docs/maintenance/VERSIONING_AND_RELEASES.md diff --git a/docs/development/architecture/PACKAGES.md b/docs/development/architecture/PACKAGES.md index f798e35b2e47..74ca39b3ae43 100644 --- a/docs/development/architecture/PACKAGES.md +++ b/docs/development/architecture/PACKAGES.md @@ -66,7 +66,7 @@ Any custom rules you write generally will be as well. [`@typescript-eslint/eslint-plugin-tslint`] is a separate ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. :::caution -**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLINT.md). +**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLint.md). ::: [`@typescript-eslint/eslint-plugin-tslint`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint diff --git a/docs/maintenance/RELEASES.md b/docs/maintenance/RELEASES.md new file mode 100644 index 000000000000..b18fbae2e4f9 --- /dev/null +++ b/docs/maintenance/RELEASES.md @@ -0,0 +1,85 @@ +--- +id: releases +sidebar_label: Releases +title: Releases +--- + +## Canary + +We release a canary version for each commit to `main` that passes all required checks. This release is performed automatically by the [`publish_canary_version` step](https://github.com/typescript-eslint/typescript-eslint/blob/5feb2dba9da2bd5e233451b7b0f1c99414b5aef9/.github/workflows/ci.yml#L234-L263). + +This release is goes to the `canary` tag on npm and it is versioned as an incremental canary patch release on top of the current `latest` version. I.e. if the current version is `5.6.1`, then the first canary version will be `5.6.2-alpha.0`, the second `5.6.2-alpha.1`, and so on. + +## Latest + +We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by an external job (TBA migration to GitHub actions). This release goes to the standard `latest` tag on npm. + +See the [versioning](#versioning) section below for how the version number is calculated. + +If there have been no commits that impact public-facing packages then a patch-level release shall be released. + +Latest releases shall only ever be "minor" or "patch" releases. + +## Major Releases + +We currently do not have a set schedule around when major releases shall be performed. +They're instead done as the need arises. + +We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`. +When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch. + +### Major Release Steps + +Our releases go through three groups of steps: + +1. [Pre-Release Preparation] +1. [Merging Breaking Changes] +1. [Releasing the Version] + +#### 1. Pre-Release Preparation + +1. Create a milestone by the name of the release [example: [Milestone 6.0.0](https://github.com/typescript-eslint/typescript-eslint/milestone/8)]. +1. If an issue for changes to recommended rule configs doesn't yet exist, create one [example: [Changes to the `recommended` sets for 5.0.0](https://github.com/typescript-eslint/typescript-eslint/issues/5900)]. +1. Add any breaking changes intended for the release to that milestone. +1. Create two new branches off `main` in the project repository (not a personal fork): + - `v${major}` + - `v${major}-canary-auto-release` +1. Send a PR from `v${major}-canary-auto-release` to `main` modifying the [`ci.yml` workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml) [example: [chore: add auto-canary release for v6](https://github.com/typescript-eslint/typescript-eslint/pull/5883)]: + - Under `pushes:` at the beginning of the file, add an `- v${major}` list item. + - Add a `publish_canary_version_v${major}` step the same as `publish_canary_version` except: + - Add the condition: `if: github.ref == 'refs/heads/v${major}'`. + - Its publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`. + +#### 2. Merging Breaking Changes + +1. Send a PR from `v${major}` to `main` [example: [v6.0.0](https://github.com/typescript-eslint/typescript-eslint/pull/5886)]. +1. Change all [breaking change PRs](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22breaking+change%22) to target the `v${major}` branch. + - To signify these changes as breaking, the first line of the PR description must read as `BREAKING CHANGE:`, and second line should briefly summarize the changes. + - It is important to note that when merged the commit message must also include `BREAKING CHANGE:` as the first line in order for lerna to recognize it as a breaking change in the release notes. If you miss this it just means more manual work when writing the release documentation. +1. Wait until all required PRs have been merged +1. Let the release wait for **at least 1 week** to allow time for early adopters to help test it and discuss the changes. + - Promote it on the [`@tseslint`](https://twitter.com/tseslint) twitter to get some additional attention. +1. Once discussions have settled, rebase merge the PR on top of `main`. + +:::note +_Non_-breaking changes can be merged to `main` or the major branch. +They don't need any special treatment. +::: + +#### 3. Releasing the Version + +1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. +1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. +1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! + +## Out-of-Band + +We will do releases "out-of-band" (outside the [latest](#latest) schedule) for rare emergencies. +We assess need on a case-by-case basis though generally an emergency is defined as a critical regression specifically introduced in the latest release. + +These releases are done manually by a maintainer with the required access privileges. + +## Back-Porting Releases + +We **_do not_** back port releases to previously released major/minor versions. +We only ever release forward. diff --git a/docs/maintenance/VERSIONING.md b/docs/maintenance/VERSIONING.md new file mode 100644 index 000000000000..799f679ac994 --- /dev/null +++ b/docs/maintenance/VERSIONING.md @@ -0,0 +1,72 @@ +--- +id: versioning +sidebar_label: Versioning +title: Versioning +--- + +We follow [semantic versioning (semver)](https://semver.org). +This page exists to help set guidelines around when what we consider to fall within each of the semver categories. + +All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations. + +When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have _very_ different API surfaces, they also are consumed in very different ways. + +Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes. + +## Internal packages + +Any packages in this project that are not part of our public API surface (such as `eslint-plugin-internal` or `website`) shall not be considered when calculating new package versions. + +## `ast-spec` and `visitor-keys` + +A change to the AST **_shall_** be considered breaking if it: + +- Removes or renames an existing AST Node. +- Removes or renames an existing property on an AST Node. +- Changes a type in a non-refining way (i.e. `string` to `number`). + +A change to the AST **_shall not_** be considered breaking if it: + +- Adds a new property to the AST. +- Adds a new node type to the AST. +- Adds a new node type to an existing union type. +- Refines a type to be more specific (i.e. `string` to `'literal' | 'union'`). +- Removes a type from a union that was erroneously added and did not match the runtime AST. + +## `eslint-plugin` and `eslint-plugin-tslint` + +A change to the plugins **_shall_** be considered breaking if it: + +- Removes or renames an option. +- Changes the default option of a rule. +- Changes a rule's schema to be stricter. +- Consumes type information to a rule that did not previously consume it. +- Removes or renames a rule. +- Changes any of the recommended configurations. +- Changes the default behavior of a rule in such a way that causes new reports in a large set of cases in an average codebase. + +A change to the plugins **_shall not_** be considered breaking if it: + +- Adds an option. +- Adds a rule. +- Deprecates a rule. +- Adds additional checks to an existing rule that causes new reports in a small-to-medium set of cases in an average codebase. +- Refactors a rule's code in a way that does not introduce additional reports. +- Changes to a rule's description or other metadata. +- Adds a fixer or suggestion fixer. +- Removes a fixer or suggestion fixer. +- Fixes incorrect behavior in a rule that may or may not introduce additional reports. + +### `parser`, `typescript-estree`, `scope-manager`, `types`, `type-utils`, `utils` + +A change to these packages **_shall_** be considered breaking if it: + +- Changes the API surface in a backwards-incompatible way (remove or rename functions, types, etc). + +A change to these packages **_shall not_** be considered breaking if it: + +- Adds to the API surface (add functions, types, etc). +- Deprecates parts of the API surface. +- Adds **_optional_** arguments to functions or properties to input types. +- Adds additional properties to output types. +- Adds documentation in the form of JSDoc comments. diff --git a/docs/maintenance/VERSIONING_AND_RELEASES.md b/docs/maintenance/VERSIONING_AND_RELEASES.md deleted file mode 100644 index a567d0efdbc7..000000000000 --- a/docs/maintenance/VERSIONING_AND_RELEASES.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: versioning-and-releases -sidebar_label: Versioning and Releases -title: Versioning and Releases ---- - -## Releases - -### Canary - -We release a canary version for each and every commit to `main` that passes all required checks. This release is performed automatically by the [`publish_canary_version` step](https://github.com/typescript-eslint/typescript-eslint/blob/5feb2dba9da2bd5e233451b7b0f1c99414b5aef9/.github/workflows/ci.yml#L234-L263). - -This release is goes to the `canary` tag on npm and it is versioned as an incremental canary patch release on top of the current `latest` version. I.e. if the current version is `5.6.1`, then the first canary version will be `5.6.2-alpha.0`, the second `5.6.2-alpha.1`, and so on. - -### Latest - -We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by an external job (TBA migration to GitHub actions). This release goes to the standard `latest` tag on npm. - -See the [versioning](#versioning) section below for how the version number is calculated. - -If there have been no commits that impact public-facing packages then a patch-level release shall be released. - -Latest releases shall only ever be "minor" or "patch" releases. - -### Major Releases - -We currently do not have a set schedule around when major releases shall be performed; instead they shall be done as the need arises. We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`. -When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch. - -
- -This section details the steps for a major release. - -1. Create a new branch off `main` called `v${major}`. This branch should be created in the project repository (not your personal fork). -1. Add a new step to [the CI workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml). This step should be exactly the same as the `publish_canary_version` step except: - 1. The publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`. - 1. The step should have the condition: `if: github.ref == 'refs/heads/v${major}'`. -1. Raise a new PR merging the new branch into `main`. - - This PR serves as documentation of the changes as well as a place for directed feedback. -1. Any breaking change PRs should have their target branch switched to this branch. - - To signify these changes as breaking changes, the first line of the PR description must read as `BREAKING CHANGE:`. - - It is important to note that when merged the commit message must also include `BREAKING CHANGE:` as the first line in order for lerna to recognize it as a breaking change in the release notes. If you miss this it just means more manual work when writing the release documentation. -1. Non-breaking changes can be merged to `main` or the major branch as desired. They do not need any special treatment. -1. Once all required PRs have been merged - let the release bake for at least 1 week to allow time for early adopters to help test it. - - Consider promoting it on the [`@tseslint`](https://twitter.com/tseslint) twitter to get some additional attention. -1. Once the RC has baked for long enough, rebase merge the PR on top of `main`. -1. Discuss with the maintainers to organize an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. -1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. -1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! - -
- -### Out-of-Band - -Rarely we will do releases "out-of-band" (outside the [latest](#latest) schedule). These releases are done manually by a maintainer with the required access privileges. - -These releases are done only in emergencies. We assess need on a case-by-case basis though generally an emergency is defined as a critical regression specifically introduced in the latest release. - -### Back-Porting Releases - -We **_do not_** back port releases to previously released major/minor versions; we only ever release forward. - -## Versioning - -In this project we follow [semantic versioning (semver)](https://semver.org/). This page exists to help set guidelines around when what we consider to fall within each of the semver categories. - -All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations. - -When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have _very_ different API surfaces, they also are consumed in very different ways. - -Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes. - -### Internal packages - -Any packages in this project that are not part of our public API surface (such as `eslint-plugin-internal` or `website`) shall not be considered when calculating new package versions. - -### `ast-spec` and `visitor-keys` - -A change to the AST **_shall_** be considered breaking if it: - -- Removes or renames an existing AST Node. -- Removes or renames an existing property on an AST Node. -- Changes a type in a non-refining way (i.e. `string` to `number`). - -A change to the AST **_shall not_** be considered breaking if it: - -- Adds a new property to the AST. -- Adds a new node type to the AST. -- Adds a new node type to an existing union type. -- Refines a type to be more specific (i.e. `string` to `'literal' | 'union'`). -- Removes a type from a union that was erroneously added and did not match the runtime AST. - -### `eslint-plugin` and `eslint-plugin-tslint` - -A change to the plugins **_shall_** be considered breaking if it: - -- Removes or renames an option. -- Changes the default option of a rule. -- Changes a rule's schema to be stricter. -- Consumes type information to a rule that did not previously consume it. -- Removes or renames a rule. -- Changes any of the recommended configurations. -- Changes the default behavior of a rule in such a way that causes new reports in a large set of cases in an average codebase. - -A change to the plugins **_shall not_** be considered breaking if it: - -- Adds an option. -- Adds a rule. -- Deprecates a rule. -- Adds additional checks to an existing rule that causes new reports in a small-to-medium set of cases in an average codebase. -- Refactors a rule's code in a way that does not introduce additional reports. -- Changes to a rule's description or other metadata. -- Adds a fixer or suggestion fixer. -- Removes a fixer or suggestion fixer. -- Fixes incorrect behavior in a rule that may or may not introduce additional reports. - -#### `parser`, `typescript-estree`, `scope-manager`, `types`, `type-utils`, `utils` - -A change to these packages **_shall_** be considered breaking if it: - -- Changes the API surface in a backwards-incompatible way (remove or rename functions, types, etc). - -A change to these packages **_shall not_** be considered breaking if it: - -- Adds to the API surface (add functions, types, etc). -- Deprecates parts of the API surface. -- Adds **_optional_** arguments to functions or properties to input types. -- Adds additional properties to output types. -- Adds documentation in the form of JSDoc comments. diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 3d5b029d2f84..fbdc1f28e6b0 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -54,7 +54,11 @@ module.exports = { }, { collapsible: false, - items: ['maintenance/issues', 'maintenance/versioning-and-releases'], + items: [ + 'maintenance/issues', + 'maintenance/releases', + 'maintenance/versioning', + ], label: 'Maintenance', link: { id: 'maintenance', From 2c67db1d79d5d65feb514d2495ff62b2103e5703 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 30 Oct 2022 23:09:36 -0400 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: Brad Zacher --- docs/maintenance/RELEASES.md | 9 +++++---- docs/maintenance/VERSIONING.md | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/maintenance/RELEASES.md b/docs/maintenance/RELEASES.md index b18fbae2e4f9..e0e646fc1176 100644 --- a/docs/maintenance/RELEASES.md +++ b/docs/maintenance/RELEASES.md @@ -12,7 +12,7 @@ This release is goes to the `canary` tag on npm and it is versioned as an increm ## Latest -We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by an external job (TBA migration to GitHub actions). This release goes to the standard `latest` tag on npm. +We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by a Github action. This release goes to the standard `latest` tag on npm. See the [versioning](#versioning) section below for how the version number is calculated. @@ -22,8 +22,7 @@ Latest releases shall only ever be "minor" or "patch" releases. ## Major Releases -We currently do not have a set schedule around when major releases shall be performed. -They're instead done as the need arises. +We currently do not have a set schedule around when major releases shall be performed; instead they are done as the need arises. We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`. When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch. @@ -44,11 +43,12 @@ Our releases go through three groups of steps: 1. Create two new branches off `main` in the project repository (not a personal fork): - `v${major}` - `v${major}-canary-auto-release` -1. Send a PR from `v${major}-canary-auto-release` to `main` modifying the [`ci.yml` workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml) [example: [chore: add auto-canary release for v6](https://github.com/typescript-eslint/typescript-eslint/pull/5883)]: +1. Raise a PR from `v${major}-canary-auto-release` to `main` modifying the [`ci.yml` workflow](https://github.com/typescript-eslint/typescript-eslint/blob/main/.github/workflows/ci.yml) [example: [chore: add auto-canary release for v6](https://github.com/typescript-eslint/typescript-eslint/pull/5883)]: - Under `pushes:` at the beginning of the file, add an `- v${major}` list item. - Add a `publish_canary_version_v${major}` step the same as `publish_canary_version` except: - Add the condition: `if: github.ref == 'refs/heads/v${major}'`. - Its publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`. + - Merge this into `main` once reviewed and rebase the `v${major}` branch. #### 2. Merging Breaking Changes @@ -70,6 +70,7 @@ They don't need any special treatment. 1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. 1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. + - Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0) 1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! ## Out-of-Band diff --git a/docs/maintenance/VERSIONING.md b/docs/maintenance/VERSIONING.md index 799f679ac994..514215d1136c 100644 --- a/docs/maintenance/VERSIONING.md +++ b/docs/maintenance/VERSIONING.md @@ -35,7 +35,7 @@ A change to the AST **_shall not_** be considered breaking if it: ## `eslint-plugin` and `eslint-plugin-tslint` -A change to the plugins **_shall_** be considered breaking if it: +A change to the plugins **_shall_** be considered breaking if it will require the user to change their config. More specifically: - Removes or renames an option. - Changes the default option of a rule. @@ -47,7 +47,7 @@ A change to the plugins **_shall_** be considered breaking if it: A change to the plugins **_shall not_** be considered breaking if it: -- Adds an option. +- Adds an option that by default does not remove existing functionality. - Adds a rule. - Deprecates a rule. - Adds additional checks to an existing rule that causes new reports in a small-to-medium set of cases in an average codebase. From c23afab330d1b1aef4697691011ebf69f17966de Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 30 Oct 2022 23:10:05 -0400 Subject: [PATCH 09/11] Update docs/maintenance/RELEASES.md --- docs/maintenance/RELEASES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maintenance/RELEASES.md b/docs/maintenance/RELEASES.md index e0e646fc1176..6f912fa5b206 100644 --- a/docs/maintenance/RELEASES.md +++ b/docs/maintenance/RELEASES.md @@ -12,7 +12,7 @@ This release is goes to the `canary` tag on npm and it is versioned as an increm ## Latest -We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by a Github action. This release goes to the standard `latest` tag on npm. +We release a latest version every Monday at 1pm US Eastern time using the latest commit to `main` at that time. This release is performed automatically by a Github action located in a private repository. This release goes to the standard `latest` tag on npm. See the [versioning](#versioning) section below for how the version number is calculated. From 1b35adae23b407554b7256809555fbcf7bff6879 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 30 Oct 2022 23:19:59 -0400 Subject: [PATCH 10/11] Ran Prettier on RELEASES.md --- docs/maintenance/RELEASES.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/maintenance/RELEASES.md b/docs/maintenance/RELEASES.md index 6f912fa5b206..211294d488bb 100644 --- a/docs/maintenance/RELEASES.md +++ b/docs/maintenance/RELEASES.md @@ -70,7 +70,9 @@ They don't need any special treatment. 1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release. 1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users. - - Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0) + +- Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0) + 1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release! ## Out-of-Band From eea220c9f8a76a4475c39b1f35be74251bb669af Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Thu, 3 Nov 2022 14:37:21 +0100 Subject: [PATCH 11/11] Update docs/development/architecture/PACKAGES.md --- docs/development/architecture/PACKAGES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/architecture/PACKAGES.md b/docs/development/architecture/PACKAGES.md index 74ca39b3ae43..f798e35b2e47 100644 --- a/docs/development/architecture/PACKAGES.md +++ b/docs/development/architecture/PACKAGES.md @@ -66,7 +66,7 @@ Any custom rules you write generally will be as well. [`@typescript-eslint/eslint-plugin-tslint`] is a separate ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint. :::caution -**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLint.md). +**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLINT.md). ::: [`@typescript-eslint/eslint-plugin-tslint`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint