diff --git a/docs/src/maintain/index.md b/docs/src/maintain/index.md index 88d537aa053..013a5a1ec0b 100644 --- a/docs/src/maintain/index.md +++ b/docs/src/maintain/index.md @@ -11,7 +11,7 @@ This guide is intended for those who work as part of the ESLint project team. ## [Manage Issues](manage-issues) -Describes how to deal with issues when they're opened, when interacting with users, and how to close them effectively. +Describes how to deal with issues when they're opened, how to interact with users who open issues, and how to close issues effectively. ## [Review Pull Requests](review-pull-requests) diff --git a/docs/src/maintain/manage-issues.md b/docs/src/maintain/manage-issues.md index 085b1083782..58cc9deb9e6 100644 --- a/docs/src/maintain/manage-issues.md +++ b/docs/src/maintain/manage-issues.md @@ -12,7 +12,7 @@ New issues are filed frequently, and how we respond to those issues directly aff ## Things to Keep in Mind -1. **Be nice.** Even if the people are being rude or aggressive on an issue, as a project team member you must be the mature one in the conversation. Do your best to work with everyone no matter their style. Remember, poor wording choice can also be a sign of someone who doesn't know English very well, so be sure to consider that when trying to determine the tone of someone's message. Being rude, even when someone is being rude to you, reflects poorly on the team and the project as a whole. +1. **Be nice.** Even if the people are being rude or aggressive on an issue, you must be the mature one in the conversation as a project team member. Do your best to work with everyone no matter their style. Remember, poor wording choice can also be a sign of someone who doesn't know English very well, so be sure to consider that when trying to determine the tone of someone's message. Being rude, even when someone is being rude to you, reflects poorly on the team and the project as a whole. 1. **Be inquisitive.** Ask questions on the issue whenever something isn't clear. Don't assume you understand what's being reported if there are details missing. Whenever you are unsure, it's best to ask for more information. 1. **Not all requests are equal.** It's unlikely we'll be able to accommodate every request, so don't be afraid to say that something doesn't fit into the scope of the project or isn't practical. It's better to give such feedback if that's the case. 1. **Close when appropriate.** Don't be afraid to close issues that you don't think will be done, or when it's become clear from the conversation that there's no further work to do. Issues can always be reopened if they are closed incorrectly, so feel free to close issues when appropriate. Just be sure to leave a comment explaining why the issue is being closed (if not closed by a commit). @@ -21,10 +21,10 @@ New issues are filed frequently, and how we respond to those issues directly aff There are four primary issue categories: -1. **Bug** - something isn't working the way it's expected to work. -1. **Enhancement** - a change to something that already exists. For instance, adding a new option to an existing rule or a bug in a rule where fixing it will result in the rule reporting more problems (in this case, use both "Bug" and "Enhancement"). -1. **Feature** - adding something that doesn't already exist. For example, adding a new rule, new formatter, or new command line flag. -1. **Question** - an inquiry about how something works that won't result in a code change. We'd prefer if people use discussions or Discord for questions, but sometimes they'll open an issue. +1. **Bug**: Something isn't working the way it's expected to work. +1. **Enhancement**: A change to something that already exists. For instance, adding a new option to an existing rule or fixing a bug in a rule where fixing it will result in the rule reporting more problems (in this case, use both "Bug" and "Enhancement"). +1. **Feature**: Adding something that doesn't already exist. For example, adding a new rule, new formatter, or new command line flag. +1. **Question**: An inquiry about how something works that won't result in a code change. We prefer if people use GitHub Discussions or Discord for questions, but sometimes they'll open an issue. The first goal when evaluating an issue is to determine which category the issue falls into. @@ -32,17 +32,17 @@ The first goal when evaluating an issue is to determine which category the issue All of ESLint's issues, across all GitHub repositories, are managed on our [Triage Project](https://github.com/orgs/eslint/projects/2). Please use the Triage project instead of the issues list when reviewing issues to determine what to work on. The Triage project has several columns: -* **Needs Triage** - issues that have not yet been reviewed by anyone -* **Triaging** - issues that someone has reviewed but has not been able to fully triage yet -* **Ready for Dev Team** - issues that have been triaged and have all of the information necessary for the dev team to take a look -* **Evaluating** - the dev team is evaluating these issues to determine whether to move forward or not -* **Feedback Needed** - a team member is requesting more input from the rest of the team before proceeding -* **Waiting for RFC** - the next step in the process is for an RFC to be written -* **RFC Opened** - an RFC is opened to address these issues -* **Blocked** - the issue can't move forward due to some dependency -* **Ready to Implement** - these issues have all of the details necessary to start implementation -* **PR Opened** - there is an open pull request for each of these issues -* **Completed** - the issue has been closed (either via pull request merge or by the team manually closing the issue) +* **Needs Triage**: Issues that have not yet been reviewed by anyone +* **Triaging**: Issues that someone has reviewed but has not been able to fully triage yet +* **Ready for Dev Team**: Issues that have been triaged and have all the information necessary for the dev team to take a look +* **Evaluating**: The dev team is evaluating these issues to determine whether to move forward or not +* **Feedback Needed**: A team member is requesting more input from the rest of the team before proceeding +* **Waiting for RFC**: The next step in the process is for an RFC to be written +* **RFC Opened**: An RFC is opened to address these issues +* **Blocked**: The issue can't move forward due to some dependency +* **Ready to Implement**: These issues have all the details necessary to start implementation +* **PR Opened**: There is an open pull request for each of these issues +* **Completed**: The issue has been closed (either via pull request merge or by the team manually closing the issue) We make every attempt to automate movement between as many columns as we can, but sometimes moving issues needs to be done manually. @@ -50,12 +50,12 @@ We make every attempt to automate movement between as many columns as we can, bu When an issue is opened, it is automatically added to the "Needs Triage" column in the Triage project. These issues need to be evaluated to determine next steps. Anyone on the support team or dev team can follow these steps to properly triage issues. -**Note:** If an issue is in the "Triaging" column, that means someone is already triaging it and you should let them finish. There's no need to comment on issues in the "Triaging" column unless someone asks for help. +**Note:** If an issue is in the "Triaging" column, that means someone is already triaging it, and you should let them finish. There's no need to comment on issues in the "Triaging" column unless someone asks for help. The steps for triaging an issue are: -1. Move the issue from "Needs Triage" to "Triaging" in the Triage project -1. Check: Has all of the information in the issue template been provided? +1. Move the issue from "Needs Triage" to "Triaging" in the Triage project. +1. Check: Has all the information in the issue template been provided? * **No:** If information is missing from the issue template, or you can't tell what is being requested, please ask the author to provide the missing information: * Add the "needs info" label to the issue so we know that this issue is stalled due to lack of information. * Don't move on to other steps until the necessary information has been provided. @@ -65,15 +65,15 @@ The steps for triaging an issue are: * If the issue is reporting a bug, try to reproduce the issue following the instructions in the issue. If you can reproduce the bug, please add the "repro:yes" label. (The bot will automatically remove the "repro:needed" label.) If you can't reproduce the bug, ask the author for more information about their environment or to clarify reproduction steps. * If the issue is reporting something that works as intended, please add the "works as intended" label and close the issue. * For all issues, please add labels describing the part of ESLint affected: - * "3rd party plugin" - related to third-party functionality (plugins, parsers, rules, etc.) - * "build" - related to commands run during a build (testing, linting, release scripts, etc.) - * "cli" - related to command line input or output, or to `CLIEngine` - * "core" - related to internal APIs - * "documentation" - related to content on eslint.org - * "infrastructure" - related to resources needed for builds or deployment (VMs, CI tools, bots, etc.) - * "rule" - related to core rules - * If you can't properly triage the issue, move the issue back to the "Needs Triage" column in the Triage project so someone else can triage it - * If you have triaged the issue, move the issue to the "Ready for Dev Team" column in the Triage project + * **3rd party plugin**: Related to third-party functionality (plugins, parsers, rules, etc.) + * **build**: Related to commands run during a build (testing, linting, release scripts, etc.) + * **cli**: Related to command line input or output, or to `CLIEngine` + * **core**: Related to internal APIs + * **documentation**: Related to content on eslint.org + * **infrastructure**: Related to resources needed for builds or deployment (VMs, CI tools, bots, etc.) + * **rule**: Related to core rules + * If you can't properly triage the issue, move the issue back to the "Needs Triage" column in the Triage project so someone else can triage it. + * If you have triaged the issue, move the issue to the "Ready for Dev Team" column in the Triage project. ## Evaluation Process @@ -81,12 +81,12 @@ When an issue has been moved to the "Ready for Dev Team" column, any dev team me 1. Move the issue into the "Evaluating" column. 1. Next steps: - * **Bugs:** if you can verify the bug, add the "accepted" label and ask if they would like to submit a pull request. - * **New Rules:** if you are willing to champion the rule (meaning you believe it should be included in ESLint core and you will take ownership of the process for including it), add a comment saying you will champion the issue, assign the issue to yourself, and follow the [guidelines](#championing-issues) below. - * **Rule Changes:** if you are willing to champion the change and it would not be a breaking change (requiring a major version increment), add a comment saying that you will champion the issue, assign the issue to yourself, and follow the [guidelines](#championing-issues) below. - * **Breaking Changes:** if you suspect or can verify that a change would be breaking, label it as "Breaking". - * **Duplicates:** if you can verify the issue is a duplicate, add a comment mentioning the duplicate issue (such as, "Duplicate of #1234") and close the issue. -1. Regardless of the above, always leave a comment. Don't just add labels, engage with the person who opened the issue by asking a question (request more information if necessary) or stating your opinion of the issue. If it's a verified bug, ask if the user would like to submit a pull request. + * **Bugs**: If you can verify the bug, add the "accepted" label and ask if they would like to submit a pull request. + * **New Rules**: If you are willing to champion the rule (meaning you believe it should be included in ESLint core and you will take ownership of the process for including it), add a comment saying you will champion the issue, assign the issue to yourself, and follow the [guidelines](#championing-issues) below. + * **Rule Changes**: If you are willing to champion the change and it would not be a breaking change (requiring a major version increment), add a comment saying that you will champion the issue, assign the issue to yourself, and follow the [guidelines](#championing-issues) below. + * **Breaking Changes**: If you suspect or can verify that a change would be breaking, label it as "Breaking". + * **Duplicates**: If you can verify the issue is a duplicate, add a comment mentioning the duplicate issue (such as, "Duplicate of #1234") and close the issue. +1. Regardless of the above, always leave a comment. Don't just add labels; engage with the person who opened the issue by asking a question (request more information if necessary) or stating your opinion of the issue. If it's a verified bug, ask if the user would like to submit a pull request. 1. If the issue can't be implemented because it needs an external dependency to be updated or needs to wait for another issue to be resolved, move the issue to the "Blocked" column. 1. If the issue has been accepted and an RFC is required as the next step, move the issue to the "Waiting for RFC" column and comment on the issue that an RFC is needed. @@ -110,7 +110,7 @@ New rules and rule changes require a champion. As champion, it's your job to: * Gain [consensus](#consensus) from the ESLint team on inclusion * Guide the rule creation process until it's complete (so only champion a rule that you have time to implement or help another contributor implement) -Once consensus has been reached on inclusion, add the "accepted" and, optionally, "help wanted" and "good first issue" labels, as necessary. +Once consensus has been reached on inclusion, add the "accepted" label. Optionally, add "help wanted" and "good first issue" labels, as necessary. ## Consensus @@ -129,9 +129,9 @@ The issue will be discussed at the next TSC meeting and the resolution will be p In addition to the above, changes to the core (including CLI changes) that would result in a minor or major version release must be approved by the TSC by standard TSC motion. Add the label "tsc agenda" to the issue and it will be discussed at the next TSC meeting. In general, requests should meet the following criteria to be considered: -1. The feature or enhancement is in scope for the project and should be added to the roadmap -1. Someone is committed to including the change within the next year -1. There is reasonable certainty about who will do the work +1. The feature or enhancement is in scope for the project and should be added to the roadmap. +1. Someone is committed to including the change within the next year. +1. There is reasonable certainty about who will do the work. When a suggestion is too ambitious or would take too much time to complete, it's better not to accept the proposal. Stick to small, incremental changes and lay out a roadmap of where you'd like the project to go eventually. Don't let the project get bogged down in big features that will take a long time to complete. diff --git a/docs/src/maintain/manage-releases.md b/docs/src/maintain/manage-releases.md index 10d681a4fd8..118edc79399 100644 --- a/docs/src/maintain/manage-releases.md +++ b/docs/src/maintain/manage-releases.md @@ -13,18 +13,20 @@ Releases are when a project formally publishes a new version so the community ca * Regular releases that follow [semantic versioning](https://semver.org/) and are considered production-ready. * Prereleases that are not considered production-ready and are intended to give the community a preview of upcoming changes. -## Release Team +## Release Manager -A two-person release team is assigned to each scheduled release. This two-person team is responsible for: +One member of the Technical Steering Committee (TSC) is assigned to manage each scheduled release. The release manager is determined at the TSC meeting the day before the release. + +The release manager is responsible for: 1. The scheduled release on Friday 1. Monitoring issues over the weekend 1. Determining if a patch release is necessary on Monday 1. Publishing the patch release (if necessary) -The two-person team should seek input from the whole team on the Monday following a release to double-check if a patch release is necessary. +The release manager should seek input from the whole team on the Monday following a release to double-check if a patch release is necessary. -At least one member of the release team needs to have access to eslint's two-factor authentication for npm in order to do a release. +The release manager needs to have access to ESLint's two-factor authentication for npm in order to do a release. ## Release Communication @@ -32,10 +34,10 @@ Each scheduled release should be associated with a release issue ([example](http ## Process -On the day of a scheduled release, the release team should follow these steps: +On the day of a scheduled release, the release manager should follow these steps: 1. Review open pull requests to see if any should be merged. In general, you can merge pull requests that: - * Have been open at least two days and have been reviewed (these are just waiting for merge). + * Have been open for at least two days and approved (these are just waiting for merge). * Important pull requests (as determined by the team). You should stop and have people review before merging if they haven't been already. * Documentation changes. * Small bugfixes written by a team member. @@ -49,19 +51,23 @@ On the day of a scheduled release, the release team should follow these steps: 1. Make a release announcement on the release issue. Document any problems that occurred during the release, and remind the team not to merge anything other than documentation changes and bugfixes. Leave the release issue open. 1. Add the `patch release pending` label to the release issue. (When this label is present, `eslint-github-bot` will create a pending status check on non-semver-patch pull requests, to ensure that they aren't accidentally merged while a patch release is pending.) -On the Monday following the scheduled release, the release team needs to determine if a patch release is necessary. A patch release is considered necessary if any of the following occurred since the scheduled release: +All release-related communications occur in the `#team` channel on Discord. + +On the Monday following the scheduled release, the release manager needs to determine if a patch release is necessary. A patch release is considered necessary if any of the following occurred since the scheduled release: * A regression bug is causing people's lint builds to fail when it previously passed. * Any bug that is causing a lot of problems for users (frequently happens due to new functionality). The patch release decision should be made as early on Monday as possible. If a patch release is necessary, then follow the same steps as the scheduled release process. -In rare cases, a second patch release might be necessary if the release is known to have a severe regression that hasn't been fixed by Monday. If this occurs, the release team should announce the situation on the release issue, and leave the issue open until all patch releases are complete. However, it's usually better to fix bugs for the next release cycle rather than doing a second patch release. +In rare cases, a second patch release might be necessary if the release is known to have a severe regression that hasn't been fixed by Monday. If this occurs, the release manager should announce the situation on the release issue, and leave the issue open until all patch releases are complete. However, it's usually better to fix bugs for the next release cycle rather than doing a second patch release. After the patch release has been published (or no patch release is necessary), close the release issue and inform the team that they can start merging in semver-minor changes again. ## Emergency Releases -In general, we try not to do emergency releases (an emergency release is unplanned and isn't the regularly scheduled release or the anticipated patch release). Even if there is a regression, it's best to wait the weekend to see if any other problems arise so a patch release can fix as many issues as possible. +An emergency release is unplanned and isn't the regularly scheduled release or the anticipated patch release. + +In general, we try not to do emergency releases. Even if there is a regression, it's best to wait until Monday to see if any other problems arise so a patch release can fix as many issues as possible. The only real exception is if ESLint is completely unusable by most of the current users. For instance, we once pushed a release that errored for everyone because it was missing some core files. In that case, an emergency release is appropriate. diff --git a/docs/src/maintain/review-pull-requests.md b/docs/src/maintain/review-pull-requests.md index 976a7fd1696..e71ef9add7b 100644 --- a/docs/src/maintain/review-pull-requests.md +++ b/docs/src/maintain/review-pull-requests.md @@ -28,10 +28,10 @@ Once the bot checks have been satisfied, you check the following: 1. Double-check that the commit message tag ("Fix:", "New:", etc.) is correct based on the issue (or, if no issue is referenced, based on the stated problem). 1. If the pull request makes a change to core, ensure that an issue exists and the pull request references the issue in the commit message. -1. Does the code follow our conventions (including header comments, JSDoc comments, etc.)? If not, please leave that feedback and reference the conventions document. +1. Does the code follow our conventions (including header comments, JSDoc comments, etc.)? If not, please leave that feedback and reference the [Code Conventions](../contribute/code-conventions) documentation. 1. For code changes: * Are there tests that verify the change? If not, please ask for them. - * Is documentation needed for the change? If yes, please let the submitter know. + * Is documentation needed for the change? If yes, please ask the submitter to add the necessary documentation. 1. Are there any automated testing errors? If yes, please ask the submitter to check on them. 1. If you've reviewed the pull request and there are no outstanding issues, leave a comment "LGTM" to indicate your approval. If you would like someone else to verify the change, comment "LGTM but would like someone else to verify." @@ -91,8 +91,8 @@ If the pull request was created from a branch on the `eslint/eslint` repository There are several times when it's appropriate to close a pull request without merging: -1. The pull request addresses an issue that is already fixed -1. The pull request hasn't been updated in 17 days +1. The pull request addresses an issue that is already fixed. +1. The pull request hasn't been updated in 17 days. 1. The pull request submitter isn't willing to follow project guidelines. In any of these cases, please be sure to leave a comment stating why the pull request is being closed. diff --git a/docs/src/maintain/working-groups.md b/docs/src/maintain/working-groups.md index 97d31dfd29f..cfb5c40ec74 100644 --- a/docs/src/maintain/working-groups.md +++ b/docs/src/maintain/working-groups.md @@ -7,7 +7,7 @@ eleventyNavigation: order: 4 --- -The ESLint TSC may form working groups to focus on a specific area of the project. +The ESLint [Technical Steering Committee](../contribute/governance#technical-steering-committee-tsc) (TSC) may form working groups to focus on a specific area of the project. ## Creating a Working Group