Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update contributor guide with new issue labels. #12003

Merged
merged 2 commits into from
Apr 20, 2023
Merged

Update contributor guide with new issue labels. #12003

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94e1bf9
Update contributor guide with new issue labels.
ehuss Apr 20, 2023
4bc8581
Fix wording
ehuss Apr 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions src/doc/contrib/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand All @@ -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
209 changes: 170 additions & 39 deletions src/doc/contrib/src/issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<style>
.label-color {
border-radius:0.5em;
}
table td:nth-child(2) {
white-space: nowrap;
}

</style>

| Labels | Color | Description |
|--------|-------|-------------|
| [A-] | <span class="label-color" style="background-color:#fbca04;">&#x2003;</span>&nbsp;Yellow | The **area** of the project an issue relates to. |
| [beta-] | <span class="label-color" style="background-color:#1e76d9;">&#x2003;</span>&nbsp;Dark Blue | Tracks changes which need to be [backported to beta][beta-backport] |
| [C-] | <span class="label-color" style="background-color:#f5f1fd;">&#x2003;</span>&nbsp;Light Purple | The **category** of an issue. |
| [Command-] | <span class="label-color" style="background-color:#5319e7;">&#x2003;</span>&nbsp;Dark Purple | The `cargo` command it is related to. |
| [E-] | <span class="label-color" style="background-color:#02e10c;">&#x2003;</span>&nbsp;Green | The **experience** level necessary to fix an issue. |
| [I-] | <span class="label-color" style="background-color:#fc2929;">&#x2003;</span>&nbsp;Red | The **importance** of the issue. |
| [O-] | <span class="label-color" style="background-color:#7e7ec8;">&#x2003;</span>&nbsp;Purple Grey | The **operating system** or platform that the issue is specific to. |
| [P-] | <span class="label-color" style="background-color:#eb6420;">&#x2003;</span>&nbsp;Orange | The issue **priority**. |
| [regression-] | <span class="label-color" style="background-color:#e4008a;">&#x2003;</span>&nbsp;Pink | Tracks regressions from a stable release. |
| [relnotes] | <span class="label-color" style="background-color:#fad8c7;">&#x2003;</span>&nbsp;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-] | <span class="label-color" style="background-color:#453574;">&#x2003;</span>&nbsp;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
58 changes: 27 additions & 31 deletions src/doc/contrib/src/process/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
22 changes: 21 additions & 1 deletion src/doc/contrib/src/process/unstable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down