How the Rust issue tracker works

1

The Rust issue tracker is a sprawling beast, with little explanation. Look at all those tags! People disagree about their meaning, ascribe their own meanings, lament not knowing what they mean or how to use them.

Today I will reveal all.

There is no canonical source for this information, so this is my opinion, but as my experience with them extends back to the dawn of time, I will assert that it is an informed opinion, and more-or-less correct.

I am not implying any judgement about whether this is a good system, just describing what is. Behold!

Tag categorization

The first thing to notice about the issue tags is that most have a categorization scheme indicated by one-letter prefixes, like A-codegen and T-libs.

In general, every issue should have at least one tag from each lettered category. The process for tagging issues differs somewhat between categories and will be explained momentarily. First though let’s talk about what they mean.

What these prefix letters mean is eternally a source of bikeshedding and confusion, and as time wears on new explanations are proposed and old ones fade to dust.

CONTRIBUTING.md has opinions about this matter.

Whether the letters are an abbreviation for a real word is mostly irrelevent - some of them definitely are, some are not, some are lost forever to the haze of time. What they mean is what matters.

This is what they mean:

  • “A-”. These are the biggest set of tags and represent the area of the codebase or project they affect. Rust has many subsystems and applying these helps people narrow down searches to those they actually work on and care about. In practice there tend to be a few that collect many issues over an extended period of time (A-codegen); and others that spring into existence during intense period of development then slowly fade away (A-iterators). Thus these tags come and go regularly, and the exact set of tags is largely based on the preferences of individual developers who want to be able to track something. It’s common for issues to have multiple “A-” tags.

  • “I-”. These tags classify the type of issue. Is it a bug (I-wrong)? A feature request (I-enhancement)? Some “I-” tags are more specific types of more general “I-” tags, but issues are generally only tagged with a single "I-" tag. For example, a bug that results in a segfault will be labeled I-crash not I-wrong even though a crash is obviously wrong. If you like you can think of “I” as standing for importance.

  • “E-”. These tags say something about the effort necessary to complete the task (E-hard), though over time they have become more expansive, indicating who is eligible to complete the task (E-help-wanted), and what more need be done (E-needstest). There is generally only one of these on any issue though sometimes E-help-wanted is (and should be) paired with a tag that more plainly indicates the difficulty.

  • “T-”. These correspond to the team responsible for the issue. Issues generally have one “T-” tag but it’s fine to have more.

  • “P-”. The priority, low, medium, high. These are generally assigned by the responsible team. The criteria for assigning these tends to have some nuance, described later.

  • “B-”. These tags represent the state of the “feature pipeline”, relating to the RFC and stability processes. I don’t recall “B” standing for anything, but suspect that it was chosen as the first free letter after “A”.

Other tags

Not all tags fit into the above letter-prefix scheme. Here’s the definition of each.

  • beta-accepted, beta-nominated. These are used for backporting patches to the beta branch.

  • final-comment-period. Used to indicate that an unstable feature is nearing stabilization (or rarely, removal). FCP is the last opportunity to make opinions known before the fate of the feature is sealed forever. The same tag is used on the rust-lang/rfcs repo to announce upcoming decisions on proposed RFCs.

  • metabug. Bugs that only track a group of related bugs. This tag tends to be used inconsistently.

  • needs-crater. Indicates that a git branch needs to be tested with the mass testing tool, crater.

  • regression-from-stable-to-{nightly,beta,stable}. Indicates the bug is a regression. These are often high-priority bugs that need to get fixed, and the tag gets updated as the bug progresses through the release train and gets closer to hitting stable.

  • relnotes. For tagging PRs that should be included in release notes. We only talk about stable features in release notes, so not for tagging unstable implementations of RFCs.

  • rust-2-breakage-wishlist. Things we would love to break but can’t because of stability guarantees. Generally these issues are closed, to come back to later.

The triage processs

People in the “Rust-Push” group on GitHub can tag issues, and this is the sole purpose of that group, the name of which is an artifact of history.

With the exception of a few process-related tags, triagers may freely apply whichever tags they think is most appropriate, at any time they wish. Tags that should only be applied by certain people at certain times (discussed below) are beta-accepted, final-comment-period, and the “P-” tags.

As soon as an issue is filed, the filer or triagers should apply the “A-”, “I-”, “E-”, “T-”, and “regression-” tags. These are general categorization tags.

The procedure for applying “P-” tags is less well-defined: only those with a broad perspective on the project are in a position to make this call, and it usually entails some measure of consensus. Basically, the process for applying these tags is at the discretion of the responsible teams and/or those with ownership over the given subsystem in the compiler. Teams are encouraged to make triage a regular part of their process and apply these tags to all issues within their purview.

Project-wide triage

Every two weeks there is an open, group triage process focused on retriaging the most high-priority bugs. The focus is on ensuring that these bugs are correctly tagged and moving forward. Those in leadership roles are encouraged to attend and lend their expertise.

Nomination

For a variety of purposes it is useful to get the attention of the responsible team. To do this, tag the issue or PR with the appropriate “T-” tag (if not already tagged), then with the I-nominated tag, then leave a comment explaining why it is nominated. This procedure is often used to request a team make a decision on some issue. Once discussed the team will remove I-nominated.

Beta backporting

To nominate a PR for a beta backport do the above and also tag it with beta-nominated. The team will discuss and decide whether to accept it or not. If not, they will simply remove the beta-nominated and I-nominated tags with an explanation. If accepted they will remove I-nominated tag and add beta-accepted. At some point in the future somebody (perhaps the original PR author) will backport the PR to the beta branch and submit a fresh PR against it. After the original PR has successfully landed, someone will merge the backport, then remove the beta-nominated tag from the original PR, leaving beta-accepted. (The “beta-” tags have tri-state logic). In practice these bugs often don’t get tagged I-nominated and the request to accept is made over IRC.

The feature pipeline

When new features are added they are given a unique feature name in order to track their stability. An accompanying “tracking issue” is opened and tagged with B-unstable. This tag lets the teams figure out which issues need to be periodically reviewed and prodded to make progress, so we can get out new features.

Many new features go through the RFC process. Tracking issues for these additionally are tagged with B-RFC-approved and their OP links to the associated RFC. Once an RFC is implemented the B-RFC-approved tag is replaced with B-RFC-implemented.

The B-unstable and B-RFC-approved tags are applied immediately upon filing the issue.

Release notes

Any PR that looks notable should be tagged relnotes so that it is easier to identify interesting PRs when preparing the release notes. This tag should only apply to features that are stable. Unstable features are not mentioned in release notes.

What every single tag means

The non-letter-prefixed tags were described in the “other tags section”, the "B-" tags described sufficiently in “the feature pipeline”, and the “T-” tags are self-evident. What remains are the bulk of the letter-prefixed tags.

“P-” tags

  • P-high - The most crital bugs. Somebody should be working on this right now and should be assigned. If nobody is assigned then it’s not high priority. It’s likely this will be less strict in the near future.
  • P-low - Bugs you never want to see again until somebody submits a PR to fix it or otherwise some new information comes to light.
  • P-medium - Bugs that are important and should be periodically retriaged to see if they are now P-high or P-low.

“I-” tags

  • I-cleanup - Represents simple debt. Make the code nicer.
  • I-compiletime - Compile-time performance bugs. Use this instead of I-slow when possible.
  • I-crash - Segfaults. Prefer over I-wrong.
  • I-enhancement - New features. Less speculative than I-wishlist.
  • I-ICE - “Internal compiler error”. Panics in the compiler. Prefer over I-wrong.
  • I-needs-decision - Somebody needs to decide whether it’s a bug, how to move forward, etc. Sometimes this is applied with other “I-” tags sometimes the decision is about whether the report is even a bug.
  • I-nominated. This tag is used to get the attention of the responsible team for purposes of triage. It is the only “I-” tag that is applied in addition to other “I-” tags, so is arguably mis-categorized.
  • I-papercut - Minor issues, nice-to-haves. Some times these are ergonomics issues which in aggregate are quite important.
  • I-slow - Run-time performance issues. Use I-compiletime for rustc perf issues.
  • I-unsound - Bugs that result in unsoundness, which in Rust generally means "memory unsoundness". Prefer to I-wrong.
  • I-wishlist - Feature requests. More speculative than I-enhancement.
  • I-wrong. Just means “bug”. Prefer more specific “I-” tags.

“E-” tags

  • E-easy - Even new contributors can do this, with guidance.
  • E-hard - Requires a developer with area expertise. Might need design decisions.
  • E-medium - Between E-easy and E-hard.
  • E-help-wanted - Indicates that we’re looking for somebody to do this work. Such bugs need to have clear instructions for how to move forward. Should be paired with other “E-” tags.
  • E-mentor - Indicates that somebody is available to mentor. The mentor should indicate in a comment they can mentor, clear instructions for how to proceed with the work, and how to contact you. Should be paired with other “E-” tags. Not paired with E-help-wanted (help wanted is implied).
  • E-needstest - The only thing left to do here is add a test.

Common “A-” tags

  • A-build - Build system.
  • A-codegen - Code generation, the “trans” pass.
  • A-debuginfo - Debug metadata output by trans.
  • A-diagnostics - rustc’s user-facing error messages and related subsystems.
  • A-docs - General documentation.
  • A-infrastructure - CI, buildbot, bors, etc. All infrastructure directly maintained by rust-lang.
  • A-lang - General matters of the language definition.
  • A-libs - Anything in the std facade.
  • A-lifetimes - Borrowed pointers, borrow checking, etc.
  • A-linkage - Linkers and their operation.
  • A-lint - The lint system.
  • A-llvm - LLVM.
  • A-macros - macro_rules!
  • A-parser - The parser, libsyntax excluding the macro expander
  • A-rustdoc - rustdoc.
  • A-syntaxext - Non-macro-rules syntax extensions.
  • A-testsuite - Maintenance of the test suite.
  • A-typesystem - Anything related to type checking and the type system.
  • A-windows - Anything related to Windows support.

Uncommon “A-” tags

These tags are used less often, and are candidates for deletion when the become useless.

  • A-borrow-checker. The borrowck compiler pass.
  • A-allocators - malloc and allocator support.
  • A-amusing - Funny bugs. Should not exist.
  • A-android
  • A-ARM
  • A-associated-items
  • A-attributes - Syntax attributes like #[whatever].
  • A-benchmarks -
  • A-bitrig - Support for the BitRig OS.
  • A-book - “The Rust Programming Language” book.
  • A-bsd - Suppport for BSD OSes.
  • A-closures
  • A-collections - The collections library.
  • A-compiler
  • A-concurrency
  • A-const-fn - const fn.
  • A-cross - Cross-compilation.
  • A-destructors - The implemeentation of Drop.
  • A-dragonflybsd - Support for DragonFlyBSD.
  • A-driver - Compiler front-end, specifically the bits that tie all the passes together.
  • A-dst - Dynamically-sized types.
  • A-ffi - extern and FFI matters.
  • A-freebsd - Support for FreeBSD.
  • A-freestanding - #[no_std]
  • A-frontend - Compiler front-end, non-specific. Grabbag.
  • A-globs - “*” imports.
  • A-grammar - Matters affecting the specification of the language grammar.
  • A-hir - The compiler’s high-level IR.
  • A-incr-comp - Incremental compilation.
  • A-inline-assembly - asm!
  • A-io - Standard library I/O.
  • A-iOS - Support for iOS.
  • A-linux - Support for Linux.
  • A-mac-osx - Support for macOS.
  • A-metadata - Relating to the metadata rustc embeds in libraries.
  • A-mips
  • A-mir - Compiler mid-level IR.
  • A-naked - Naked function support.
  • A-netbsd - Support for NetBSD.
  • A-nomicon - The Rustonomicon, documentation.
  • A-openbsd - Support for OpenBSD.
  • A-optimization
  • A-plugin - Plugins. More specific than A-macros, A-syntaxext.
  • A-pretty - The rustc pretty-printer.
  • A-refactor - Suggestions to refactor things.
  • A-resolve - rustc name resolution.
  • A-runtime - The standard library runtime layer, or what’s left of it.
  • A-rustbook - The rustbook tool.
  • A-rustbuild - The rustbuild build system, makefile replacement.
  • A-security - Issues with security implications.
  • A-servo - Issues that servo cares about.
  • A-specialization - Method specialization.
  • A-spurious - Spurious failures.
  • A-stability - The implementation of feature-gating and stability tracking.
  • A-tools - Anything related to in-tree tools. Grabbag.
  • A-traits
  • A-unicode
  • A-visibility - Item visibility and privacy.
  • A-windows-gnu - GNU toolchain specific issues on Windows.
  • A-windows-msvc - MSVC toolchain specific issues on Windows.
  • A-x86
  • A-x86_64
12 Likes
2

Would this be good to place in a wiki page on github?

1 Like
3

Did you know that at one point Rust did have a wiki on Github which had a page like this? That wiki was killed off by @steveklabnik

4

https://forge.rust-lang.org/ is where stuff like this goes now.

1 Like
5

(I mean, I’d be happy to have it in the official docs in some capacity, but that’s apparently where this kind of thing should go today)

6

@steveklabnik I don’t know how much I’d trust anything on FRLO. It has its own page for platform support which is quite outdated compared to the table in the rust book on getting started.

7

.[quote=“steveklabnik, post:4, topic:3951, full:true”] https://forge.rust-lang.org/ is where stuff like this goes now. [/quote]

Perhaps CONTRIBUTING.md should add a link to this.

8

I sometimes use I-needs-decision to indicate not that no other I-tag applies, but that the right way forward is unclear. i.e., for some given unsound behavior, we might all agree it's a bug, but not on how to fix it. In those cases, there may be another I- tag that applies. Hence, like I-nominated, I think that I-needs-decision is a kind of orthogonal tag.

I'm curious about E-help-wanted vs E-mentor. I don't understand why they would be exclusive?

On a related note, my philosophy on E-mentor lately has been that, if you sign up to E-mentor, you should not only leave a comment indicating your willingness to mentor, you should take the time to write up a comment with enough detail to get somebody started (at least) on fixing the bug, and also leave a few details on how you can be contacted (e.g., your IRC nick), since I think new people to the project won't necessarily know that information. Granted, I've only done this on a few issues, but it seems to be correlated with a much higher rate of people actually following up, so I do think it's something we ought to do. :slight_smile:

In general, I think we ought to make adding a write-up part of the expectation for mentoring.

9

Linking means it doesn't work offline; it's much better if it's in-tree.

10

Hm… shouldn’t I-needs-decision and needs-crater be E- tags?

11

This is the right place today.

My intent is for that info to live on the forge and not in the book. Obviously needs work though.

Oops. I didn't mean to imply I-needs-decision means no other tag applies, just that as a consequence of needing a decision no other tag applies, though I see that's not quite true. I've updated it to reflect what you said.

To me E-mentor implies that help is wanted.

I've updated the text to this effect.

Possibly, yes. Though I might suggest that all the 'exception' cases here might just ought be their own tags: needs-decision, nominated, mentor, help-wanted.

12

For searching purposes it would be easier for all mentor bugs to be tagged help-wanted so people can just search help-wanted. But that doesn't seem to be the convention today (and it's not what I do).

13

The compiler team was using the I- tags differently:

  • I-ICE - the compiler ICEs.
  • I-crash - the compiler crashes without an ICE.
  • I-unsound - the compiler does not error out on illegal programs that cause unsoundness.
  • I-wrong - the compiler generates wrong code for legal programs.
  • I-compiletime - the compiler is slow.
  • I-slow - the compiler generates slow code.
  • I-enhancement - the compiler lacks a feature.

We do not have tags for:

  • the compiler accepts dubious code, but that does not cause unsoundness.
  • the compiler errors out on legal code.
  • the compiler issues a bad diagnostic (tho we use A-diagnostics for that).
14

It looks to me like all of those interpretations are consonant with mine except for I-wrong.

15

I'm not talking about the issue tags, what I mean is FRLO is currently almost invisible since it can't easily be found. Hard to discover ⇒ Less incentive to maintain ⇒ Easily outdated ⇒ etc. Adding FRLO to the Helpful Links and Information section shouldn't be harmful.

16

Agreed -- I feel like it's failed to really get off the ground for this reason, which is a shame, because it has a lot of potential. We should try to increase awareness for sure.

17

Sure, but I think in terms of GH queries, and I can easily imagine someone searching for all "E-help-wanted" issues -- in that case, I would want them to also find E-mentor issues. I am not totally convinced that E-mentor even needs to exist, tbh, I think it might be better served with just leaving a comment that should be enough to get people started and then linking to that comment prominently from the head of the issue (a bot could help here, by allowing people to easily write a "mentor" comment that gets auto-linked).

18

I prefer this.

19

This seems to me to be a bit surprising. Certainly the "plain English meaning" of "wrong" is more expansive. I guess I would expect that A-codegen and I-wrong simultaneously probably imply wrong codegen, but that (e.g.) A-diagnostics and I-wrong might imply "the error message contains incorrect information" or A-const-fn and I-wrong might imply some wrong behavior specific to const fns.

20

It’s about the consequence: “I-wrong” means “your code compiles but does the wrong thing” (as opposed to “your code incorrectly fails to compile” or “your code correctly fails to compile but the diagnostic is bogus”).

People (e.g. my employer) are terrified of these bugs and not without good reason.

1 Like