diff --git a/src/doc/contrib/src/index.md b/src/doc/contrib/src/index.md index 5ab169ea799..848b0efaa46 100644 --- a/src/doc/contrib/src/index.md +++ b/src/doc/contrib/src/index.md @@ -5,8 +5,8 @@ overview of how to contribute to Cargo, how to dive into the code, and how the testing infrastructure works. There are many ways to contribute, such as [helping other users], [filing -issues], [improving the documentation], [fixing bugs], and working on [small] -and [large features]. +issues], [improving the documentation], [triaging issues], [fixing bugs], and +working on [small] and [large features]. If you have a general question about Cargo or its internals, feel free to ask on [Zulip]. @@ -24,6 +24,7 @@ Please also read the [Rust Code of Conduct]. [rustup]: https://rust-lang.github.io/rustup/ [git]: https://git-scm.com/ [improving the documentation]: https://github.com/rust-lang/cargo/tree/master/src/doc -[fixing bugs]: process/index.md#working-on-small-bugs +[fixing bugs]: process/index.md#working-on-issues [small]: process/index.md#working-on-small-features [large features]: process/index.md#working-on-large-features +[triaging issues]: issues.md#triaging-issues diff --git a/src/doc/contrib/src/issues.md b/src/doc/contrib/src/issues.md index 8fc69544c61..b82492d2785 100644 --- a/src/doc/contrib/src/issues.md +++ b/src/doc/contrib/src/issues.md @@ -57,53 +57,184 @@ necessary. ## Issue labels [Issue labels] are very helpful to identify the types of issues and which -category they are related to. The Cargo team typically manages assigning -labels. The labels use a naming convention with short prefixes and colors to -indicate the kind of label: +category they are related to. -* Yellow, **A**-prefixed labels state which **area** of the project an issue - relates to. +Anyone can apply most labels by posting comments with a form such as: -* Light purple, **C**-prefixed labels represent the **category** of an issue. - In particular, **[C-feature-request]** marks *proposals* for new features. If - an issue is **C-feature-request**, but is not **[Feature accepted]** or - **[I-nominated]**, then it was not thoroughly discussed, and might need some - additional design or perhaps should be implemented as an external subcommand - first. Ping @rust-lang/cargo if you want to send a PR for such issue. +```text +@rustbot label: +A-doctests, -A-dependency-resolution +``` -* Dark purple, **Command**-prefixed labels mean the issue has to do with a - specific cargo command. +This example will add the [`A-doctests`] label and remove the +[`A-dependency-resolution`] label. -* Green, **E**-prefixed labels indicate the level of **experience** or - **effort** necessary to fix the issue. **[E-mentor]** issues also - have some instructions on how to get started. Generally, all of the - **E**-prefixed labels are issues that are ready for someone to contribute - to! +[Issue labels]: https://github.com/rust-lang/cargo/labels +[`A-doctests`]: https://github.com/rust-lang/cargo/labels/A-doctests +[`A-dependency-resolution`]: https://github.com/rust-lang/cargo/labels/A-dependency-resolution + +The labels use a naming convention with short prefixes and colors to indicate +the kind of label: + + + +| Labels | Color | Description | +|--------|-------|-------------| +| [A-] |   Yellow | The **area** of the project an issue relates to. | +| [beta-] |   Dark Blue | Tracks changes which need to be [backported to beta][beta-backport] | +| [C-] |   Light Purple | The **category** of an issue. | +| [Command-] |   Dark Purple | The `cargo` command it is related to. | +| [E-] |   Green | The **experience** level necessary to fix an issue. | +| [I-] |   Red | The **importance** of the issue. | +| [O-] |   Purple Grey | The **operating system** or platform that the issue is specific to. | +| [P-] |   Orange | The issue **priority**. | +| [regression-] |   Pink | Tracks regressions from a stable release. | +| [relnotes] |   Light Orange | Marks issues or PRs that should be highlighted in the [Rust release notes] of the next release. | +| [S-] | Varies | Tracks the **status** of issues and pull requests (see [Issue status labels](#issue-status-labels)) | +| [Z-] |   Dark Blue | Unstable, [nightly features]. | + + +[A-]: https://github.com/rust-lang/cargo/labels?q=A +[beta-]: https://github.com/rust-lang/cargo/labels?q=beta +[beta-backport]: https://forge.rust-lang.org/release/backporting.html#beta-backporting-in-rust-langcargo +[C-]: https://github.com/rust-lang/cargo/labels?q=C +[Command-]: https://github.com/rust-lang/cargo/labels?q=Command +[E-]: https://github.com/rust-lang/cargo/labels?q=E +[I-]: https://github.com/rust-lang/cargo/labels?q=I +[nightly features]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html +[O-]: https://github.com/rust-lang/cargo/labels?q=O +[P-]: https://github.com/rust-lang/cargo/labels?q=P +[regression-]: https://github.com/rust-lang/cargo/labels?q=regression +[relnotes]: https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes +[Rust release notes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md +[S-]: https://github.com/rust-lang/cargo/labels?q=S +[Z-]: https://github.com/rust-lang/cargo/labels?q=nightly -* Red, **I**-prefixed labels indicate the **importance** of the issue. The - **[I-nominated]** label indicates that an issue has been nominated for - prioritizing at the next triage meeting. +### Issue status labels -* Purple gray, **O**-prefixed labels are the **operating system** or platform - that this issue is specific to. +The `S-` prefixed *status* labels are the primary mechanism we use to track +what is happening with an issue and what it is waiting on. The following is a +list of the status labels and what they mean. This is listed roughly in the +order that an issue might go through, though issues will often jump to +different steps, or in rare cases have multiple statuses. -* Orange, **P**-prefixed labels indicate a bug's **priority**. +* **[S-triage]** --- New issues get this label automatically assigned to them + to indicate that nobody has yet looked at them, and they need someone to + assign other labels and decide what the next step is. -* **S**-prefixed labels are "status" labels, typically used for PRs, but can - also indicate an issue is **[S-blocked]**. +* **[S-needs-info]** --- Needs more info, such as a reproduction or more + background for a feature request. -* The light orange **[relnotes]** label marks issues that should be highlighted - in the [Rust release notes] of the next release. + Anyone is welcome to help with providing additional info to help reproduce + or provide more detail on use cases and such. But usually this is a request + to the initial author. -* Dark blue, **Z**-prefixed labels are for unstable, [nightly features]. + When adding this label, there should also usually be a comment that goes + along with it stating the information requested. + +* **[S-needs-team-input]** --- Needs input from team on whether/how to + proceed. + + Here it is essentially blocked waiting for a team member to move it to the + next stage. + +* **[S-needs-design]** --- Needs someone to work further on the design for the + feature or fix. + + Anyone is welcome to help at this stage, but it should be clear that it is + not yet accepted. It is expected that people should contribute comments and + ideas to the issue which furthers the process of fleshing out what is + needed, or alternate ideas. This may also require reaching out to the wider + community via forums and such. + +* **[S-needs-rfc]** --- Needs an [RFC] before this can make more progress. + + Anyone is welcome to help at this stage, but it should be clear that it is + not yet accepted. However, this should only be tagged for changes that are + somewhat likely to be accepted. + +* **[S-needs-mentor]** --- Needs a Cargo team member to commit to helping and + reviewing. + + This is for something that is accepted, such as after an RFC or a team + discussion, or an obvious issue that just needs fixing, but no team member + is available to help or review. + +* **[S-accepted]** --- Issue or feature is accepted, and has a team member + available to help mentor or review. + +* **[S-waiting-on-feedback]** --- An implemented feature is waiting on + community feedback for bugs or design concerns. + + This is typically used on a [tracking issue] after it has been implemented + to indicate what it is waiting on. + + +[S-triage]: https://github.com/rust-lang/cargo/labels/S-triage +[S-needs-info]: https://github.com/rust-lang/cargo/labels/S-needs-info +[S-needs-team-input]: https://github.com/rust-lang/cargo/labels/S-needs-team-input +[S-needs-design]: https://github.com/rust-lang/cargo/labels/S-needs-design +[S-needs-rfc]: https://github.com/rust-lang/cargo/labels/S-needs-rfc +[S-needs-mentor]: https://github.com/rust-lang/cargo/labels/S-needs-mentor +[S-accepted]: https://github.com/rust-lang/cargo/labels/S-accepted +[S-waiting-on-feedback]: https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback +[RFC]: https://github.com/rust-lang/rfcs/ +[tracking issue]: https://github.com/rust-lang/cargo/labels/C-tracking-issue + +## Triaging issues + +Triaging issues involves processing issues to assign appropriate labels, make +sure the issue has sufficient information, and to decide the next steps. +When new issues are filed, they should automatically get the [S-triage] label +assuming the author uses one of the templates. This helps identify which +issues have not yet been triaged. + +There are several things to consider when triaging an issue: + +* Is this a duplicate? Search the issue tracker (including closed issues) to + see if there is something similar or identical to what is reported. If it is + obviously a duplicate, write a comment that it is a duplicate of the other + issue, and close the issue. If it isn't obvious that it is a duplicate, + leave a comment asking the author if the other issue covers what they reported. + +* For a bug, check if the report contains enough information to reproduce it. + If you can't reproduce it, solicit more information from the author to + better understand the issue. + Change the label from [S-triage] to [S-needs-info] if this is the case. + +* Add labels that describe what the issue is related to. + + * Add the appropriate [A-], [Command-], [O-], and [Z-] prefixed labels. + * If this is a regression from stable, add one of the [regression-] + prefixed labels (depending on if it is a regression in an already + released stable release, or it is in nightly). -[Issue labels]: https://github.com/rust-lang/cargo/labels -[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy -[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor -[I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated -[C-feature-request]: https://github.com/rust-lang/cargo/labels/C-feature-request -[Feature accepted]: https://github.com/rust-lang/cargo/labels/Feature%20accepted -[S-blocked]: https://github.com/rust-lang/cargo/labels/S-blocked -[Rust release notes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md -[nightly features]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html -[relnotes]: https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes +* Assuming the issue looks valid, remove the [S-triage] label and move it onto + a new status: + + * [S-needs-rfc] --- This is a large feature request that will require a + public design process. + * [S-needs-design] --- The resolution of the issue or small feature request + will need more work to come up with the appropriate design. + * [S-needs-team-input] --- The next steps are not clear, and the Cargo team + needs to discuss whether or not to proceed and what needs to be done to + address the issue. + * [S-needs-mentor] --- This is something the Cargo team wants to address, + but does not currently have the capacity to help with reviewing. + * [S-accepted] --- This is something that clearly needs to be addressed, and + a Cargo team member has volunteered to help review. + +Anyone is welcome to help with the triaging process. You can help with +reproducing issues, checking for duplicates, gathering more information from +the reporter, assigning labels using [`@rustbot` comments](#issue-labels), and +creating a test using [Cargo's testsuite] ([example][cargotest-example]). + +[Cargo's testsuite]: tests/writing.md +[cargotest-example]: https://github.com/rust-lang/cargo/issues/11628#issuecomment-1411088951 diff --git a/src/doc/contrib/src/process/index.md b/src/doc/contrib/src/process/index.md index 348c49ba944..af019659b90 100644 --- a/src/doc/contrib/src/process/index.md +++ b/src/doc/contrib/src/process/index.md @@ -38,44 +38,40 @@ The [RFC Project Board] is used for tracking [RFCs]. [RFC Project Board]: https://github.com/rust-lang/cargo/projects/2 [RFCs]: https://github.com/rust-lang/rfcs/ -## Working on small bugs +## Working on issues -Issues labeled with the [E-help-wanted], [E-easy], or [E-mentor] [labels] are -typically issues that the Cargo team wants to see addressed, and are -relatively easy to get started with. If you are interested in one of those, -and it has not already been assigned to someone, leave a comment. See [Issue +Issues labeled with the [S-accepted] [label] are typically issues that the +Cargo team wants to see addressed. If you are interested in one of those, and +it has not already been assigned to someone, leave a comment. See [Issue assignment](#issue-assignment) below for assigning yourself. -If there is a specific issue that you are interested in, but it doesn't have -one of the `E-` labels, leave a comment on the issue. If a Cargo team member -has the time to help out, they will respond to help with the next steps. +When possible, the Cargo team will try to also include [E-easy], [E-medium], +or [E-hard] labels to try to give an estimate of the difficulty involved with +the issue. -[E-help-wanted]: https://github.com/rust-lang/cargo/labels/E-help-wanted -[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy -[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor -[labels]: ../issues.md#issue-labels - -## Working on large bugs - -Some issues may be difficult to fix. They may require significant code -changes, or major design decisions. The [E-medium] and [E-hard] [labels] can -be used to tag such issues. These will typically involve some discussion with -the Cargo team on how to tackle it. +If there is a specific issue that you are interested in, but it is not marked +as [S-accepted], leave a comment on the issue. If a Cargo team member has the +time to help out, they will respond to help with the next steps. +[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy [E-medium]: https://github.com/rust-lang/cargo/labels/E-medium [E-hard]: https://github.com/rust-lang/cargo/labels/E-hard +[S-accepted]: https://github.com/rust-lang/cargo/labels/S-accepted +[label]: ../issues.md#issue-labels ## Working on small features Small feature requests are typically managed on the [issue tracker][issue-feature-request]. Features that the Cargo team have approved -will have the [Feature accepted] label or the [E-mentor] label. If there is a -feature request that you are interested in, feel free to leave a comment -expressing your interest. If a Cargo team member has the time to help out, -they will respond to help with the next steps. Keep in mind that the Cargo -team has limited time, and may not be able to help with every feature request. -Most of them require some design work, which can be difficult. Check out the -[design principles chapter] for some guidance. +will have the [S-accepted] label. + +If there is a feature request that you are interested in, but it is not marked +as [S-accepted], feel free to leave a comment expressing your interest. If a +Cargo team member has the time to help out, they will respond to help with the +next steps. Keep in mind that the Cargo team has limited time, and may not be +able to help with every feature request. Most of them require some design +work, which can be difficult. Check out the [design principles chapter] for +some guidance. ## Working on large features @@ -114,11 +110,11 @@ The Cargo project uses several bots: ## Issue assignment -Normally, if you plan to work on an issue that has been marked with one of the -`E-` tags or [Feature accepted], it is sufficient just to leave a comment that -you are working on it. We also have a bot that allows you to formally "claim" -an issue by entering the text `@rustbot claim` in a comment. See the -[Assignment] docs on how this works. +Normally, if you plan to work on an issue that has been marked with the +[S-accepted] label, it is sufficient just to leave a comment that you are +working on it. We also have a bot that allows you to formally claim an issue +by entering the text `@rustbot claim` in a comment. See the [Assignment] docs +on how this works. [Assignment]: https://github.com/rust-lang/triagebot/wiki/Assignment diff --git a/src/doc/contrib/src/process/unstable.md b/src/doc/contrib/src/process/unstable.md index d59b9aa3429..9b05efc2e1e 100644 --- a/src/doc/contrib/src/process/unstable.md +++ b/src/doc/contrib/src/process/unstable.md @@ -33,10 +33,30 @@ typically created when a PR is close to being merged, or soon after it is merged. Use the [tracking issue template] when creating a tracking issue. Larger features should also get a new label in the issue tracker so that when -issues are filed, they can be easily tied together. +issues are filed, they can be easily tied together. Typically this would be +one of the `Z-` prefixed labels for nightly features. + +When opening a tracking issue, be sure to also add an `S-` status label to +indicate what needs to happen for it to move forward: + +* [S-needs-mentor] --- The feature isn't yet implemented, and needs a Cargo + team member to commit to helping guide and review the implementation. +* [S-accepted] --- The feature isn't yet implemented, and has a Cargo team + member willing to help review the implementation. +* [S-waiting-on-feedback] --- After the feature has been implemented, this + label indicates that it is waiting on community feedback for bugs or design + concerns. + +Tracking issues may have multiple status labels if necessary, for example if +something is only partially implemented, it may have both +[S-waiting-on-feedback] (for what is implemented) and [S-needs-mentor] or +[S-accepted] to finish the rest of the work. [tracking issue]: https://github.com/rust-lang/cargo/labels/C-tracking-issue [tracking issue template]: https://github.com/rust-lang/cargo/issues/new?labels=C-tracking-issue&template=tracking_issue.md +[S-needs-mentor]: https://github.com/rust-lang/cargo/labels/S-needs-mentor +[S-accepted]: https://github.com/rust-lang/cargo/labels/S-accepted +[S-waiting-on-feedback]: https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback ## Pre-Stabilization