Rust Forge

Welcome to the Rust Forge! Rust Forge serves as a repository of supplementary documentation useful for members of The Rust Programming Language. If you find any mistakes, typos, or want to add to the Rust Forge, feel free to file an issue or PR on the Rust Forge GitHub.

Help Wanted

Want to contribute to Rust, but don’t know where to start? Here’s a list of rust-lang projects that have marked issues that need help and issues that are good first issues.

Current Release Versions

See the release process documentation for details on what happens in the days leading up to a release.

No Tools Breakage Week

To ensure the beta release includes all the tools, no tool breakages are allowed in the week before the beta cutoff (except for nightly-only tools).

External Links

• Bibliography of research papers and other projects that influenced Rust.
• Rust Pontoon is a translation management system used to localize the Rust website.

Onboarding to the Project

This document is a starting point for a new team member (or a refresh for existing team members) on things that are useful to know as a member of the project, in particular in terms of where to raise concerns or get help.

Joining a team

Each team has different policies for joining new team members, as well as different responsibilities once you join. For now, you should talk to a team lead to learn what the team’s policy is (and please encourage them to document the policy here!). In general, most teams expect you to at least:

• Contribute to the team for at least a couple months before joining
• Respond within a reasonable time to Final Comment Periods on RFCs and PRs.

Joining wg-triage

One exception to the above is wg-triage, which we highly recommend as an introduction to working on the project. wg-triage works on triaging issues and PRs in the rust-lang/rust repository, and does not require prior experience with programming or compilers. Feel free to join wg-triage if you have ever interacted with the Rust project (interacting frequently enough that we recognize you is encouraged but not required).

To join this team, simply talk to Dylan-DPC and then open a PR to rust-lang/team. See team#1826 for an example of what changes to make.

For more information about wg-triage, see Triage Procedure.

Relationship to Council

The Leadership Council formally takes positions on behalf of the Project when needed. All Rust project members are officially represented by approximately one member of the council (some teams parent up to two or more members).

Generally speaking, any concerns you have that are either more widely applicable (i.e., not just your team) or you feel aren’t being fully handled within your team can be escalated to the Council. Note that interpersonal concerns and/or code of conduct violations should always be directed to the Moderation team.

Escalating to the Council can be done via:

• GitHub, via a new issue. This will get discussed at the regular council meeting (to which all project members are invited).
• Zulip, on #council.
• Zulip DM, to your council representative (see council for which team each representative represents).

Either can be a reasonable starting point, please select what you feel more comfortable with, though bias towards being public.

Leadership Council positions are elected by the Project teams on a rotating calendar; see Council term limits for more details.

Relationship to Foundation

The Foundation works to support the Project, and the Project has direct representation on the Foundation’s board (the 5 Project directors). Those directors are selected by the Leadership Council per the bylaws.

Those directors have 50% of the vote on any Board vote in the Foundation, regardless of the number of non-Project directors.

The website has the current Project directors.

Please reach out whether you’re just interested, have questions, or have concerns in:

• Zulip, on #foundation.
• To the Council (see above).
• To one of the Project Directors (see member list above), recommending Zulip DM as an initial point.

Platforms

Rust uses a number of different platforms for organizing work and internal communications between teams. This does not currently seek to be an exhaustive list, rather documenting the policies for a select few platforms used by the teams.

Twitter

The Rust project has a number of official Twitter accounts, credentials for which are currently maintained by the infrastructure team.

• @rustlang
• @RustStatus
• @cratesiostatus
• @rustasync

Twitter Guidelines

The project runs the Twitter account @rustlang. The account is handled by a small team of volunteers.

The account will mostly tweet links to the Rust blog and Rust Insiders blog. Additionally it will retweet:

• links to blog posts about Rust, retweeting the original author if possible
• questions about Rust, so all followers can help
• Meetup or conference announcements
• announcements of new Rust projects
• anything else relevant

We will not retweet:

• content that bashes other programming languages/projects or is otherwise unconstructive in its discussion of language/tech choice
• Personal announcements (“Today I start my job at $COMPANY writing Rust”)
• Learning Rust updates (“Today I started to learn Rust”)

The Direct Messages are open to everyone. If someone wants something retweeted, they should send the tweet via DM. The vast majority of these things should be retweeted, keeping it to the above rules. Requests of an author via DM or Tweet to not retweet something will be honored.

Additionally account handlers may look through the #rustlang hashtag for noteworthy content.

The account will only follow a small number of Project-owned/related Twitter accounts. At the time of writing (February 2022) this is only @cratesiostatus and @rust_foundation.

Access

Currently access to all four accounts is granted together via a 1password vault; we don’t split this into more fine-grained access. Some automation uses API keys of the status accounts to automatically tweet about upcoming events on crates.io.

Access is limited to a small set of folks in the twitter marker team; this isn’t automated (changes should ping infra admins for provisioning access).

People with access to 1password should:

• Never change the password or take other administrative action (this is only to be done by infra admins)
• Exclusively use the project-hosted instance to keep a copy of the password (don’t save it to any other password database, including in browser)
• Never share the password with others (even if they’re in the list)
  • All access should always go through regular channels to ensure we’re not accidentally leaking the password by passing it through unsecure channels (e.g., email)
• Be aware that the password may change regularly (requiring re-authorization)

If you believe you should have access, please file a PR against the team repository requesting it and note in the description that you’ve read this policy.

Discord

Rust’s Discord is currently used by a variety of teams such as Community, Ops, and Documentation, as well as their working groups. It is also maintained as a communication tool for Domain Working Groups, and provides a space for general discussion among Rust users, contributors, and beginners.

Where to go for help with using Discord

Discord’s support center provides documentation about its user interface and account settings.

Getting started

1. Understand community standards
   Discord, like all official Rust spaces, is governed by the Code of Conduct. Before joining the conversation there, you can prepare by reading the Code of Conduct and Moderation Guidelines. It is also useful to read Discord’s Community Guidelines

2. Access channels
   To access the Rust Discord, visit https://discord.gg/rust-lang. If you do not already have a Discord account, you can register for one as part of the process of gaining access. Your first action should be agreeing to our Code of Conduct by following the instructions in #welcome.

3. Configure notifications
   It is a good idea to disable notifications for channels that are not relevant to you, so that you will not be overwhelmed with messages. Select the expansion arrow next to the server name banner (titled “The Rust Programming Language”) and select Notifications from the dropdown. Then follow the configuration instructions provided on the Discord Support site.

Appropriate conversation

Discussions should be related to the channel purpose. On team channels, conversation should be related to team business. All channels are expected to be used for purposes related to the Rust project. Discussion of (for example) wildlife or sightseeing are not appropriate.

Channels

The following channels are relevant to newcomers to the Rust project:

• welcome - Where you agree to the CoC.
• rust-usage - This is a channel where you can access support for resolving specific language use questions. The Rust Users Forum is also relevant to your needs.
• beginners - Here, you can meet people who began using Rust relatively recently.
• contribute - Interested in contributing to the Rust project? In addition to joining this channel, you can subscribe to the This Week In Rust newsletter, where many opportunities are regularly posted. It may also help to find out more about specific teams.

Channels outside of General are for contributors to Rust.

Messages

Discord conversation takes place when people are available, so you should not generally expect that your messages will receive a response quickly unless a meeting is taking place. Depending on how your notifications are configured, you will see a red circle on top of the Discord icon in your system tray when new messages are received. If you wish to communicate with a specific individual, right-click on their user icon and select “Message” in the dropdown menu.

Read-only view

Set up a Discord account (as described in Getting Started, above) in order to access Discord. There is not currently a read-only archive view available.

Email

While most of Rust’s discussion happens on other platforms, email is eternal and we occasionally need a way to approach individuals or groups privately. Our email is hosted through Mailgun (provided by Mozilla). We create and edit the mailing lists for teams through the rust-lang/team repository. Our email domain is rust-lang.org, e.g. ferris@rust-lang.org.

Sending a public broadcast

If your teams need to reach everyone in the Rust organisation, they can send an email to all@. It is recommended that you only use this mailing list when you know that you need to contact every member, such as for organising a members event like the All Hands, or for security alerts.

Keeping responses private

When sending a message to all@, do not put all@ in To. This will mean that any replies to your broadcast will also be sent to everyone. Instead, put your team’s email address in To field, and place all@ in the Bcc field. Then any replies will be sent to just your team.

GitHub

GitHub is where the Rust project hosts all of its code, as well as large parts of its discussions.

Organisations

• rust-lang — The Rust project organisation.
• rust-embedded — The Embedded Working Group organisation.
• rustwasm — The WebAssembly Working Group organisation.
• rust-cli — The Command Line Application Working Group organisation.
• rust-secure-code — The Secure Code Working Group organisation.
• rust-gamedev — The Game Development Working Group organisation.

rust-lang organization policy

The following is the policy for management of the rust-lang organization.

Access

All access to the rust-lang GitHub organization is managed via the team repository¹. Teams that want to assign access levels, or create new repositories should open a Pull Request to that repository to request the change.

The Infrastructure Team is responsible for overall administration of the rust-lang GitHub organization. Selected members of the Infrastructure Team may be organization owners if their work requires it.

All GitHub accounts used to interact with the Rust-Lang GitHub organization (owner or non-owner) must have 2FA enabled. This is enforced by GitHub.

Bot accounts controlled by the Infrastructure Team (such as the triagebot) can be granted any level of access required for them to work at the discretion of the Infrastructure Team.

1. See Team Maintenance for policy on how the team repo is managed. ↩

Zulip

Rust’s Zulip is used by a number of teams, notably the compiler, language, and library teams, along with their working groups.

Zulip can be an unintuitive platform to get started with. To get started, take a look at the getting started guide. For more detail, examine the Zulip user documentation!

Where to go for help with using Zulip

If you’re testing a feature, or want to get help, the #zulip stream is the place to go. Like elsewhere, the best thing to do is to create a new topic for each question.

Getting started

It is recommended to first look at the official getting started guide. Like Rust itself, Zulip is a bit special and reading the documentation before digging can be really helpful.

You’ll definitely want to configure the streams that you’re subscribed to when getting started; the default set is quite limited, and there are many groups that exist beyond it. Subscribing to a stream is very low cost – it is similar to being “in” an IRC channel, except that logs are available for all streams, regardless of subscription status.

It’s not necessary to introduce yourself, but feel free to say hello in the #new members stream.

User groups

User groups can be pinged by anyone with the @<group> notation, same as pinging another user. Groups can be created by anyone, and anyone can join a group.

Users should feel free to join (or leave) groups on their own. Furthermore, users should feel free to create groups as needed, though it is currently expected that this is somewhat rare. You should name your group similar to how you would name a stream for the same purpose, though groups can be more fine-grained (or less). For example, @T-compiler/meeting currently does not have a dedicated stream.

Appropriate conversation

In most streams, you should try to keep conversations related to team business. The #general stream is a bit broader, but even there, discussions should be closely related to Rust (though may not relate to projects of any particular team). All channels are expected to be used for discussions related to the Rust project, though; discussions of (for example) wildlife or sightseeing are not appropriate.

Streams

These are similar to “channels” on other platforms (i.e., there should not be too many). On the other hand, you can choose which streams you subscribe to, so there can be more than channels on other platforms. Read Zulip’s documentation for more details.

Streams are appropriate for any Rust official group. For example, working groups, project groups, teams are all examples of official groups. These should ideally also be represented in the team repository.

Default streams

This section is still under debate, and it is not yet clear which direction we will go. It is non-normative, and should not be used yet for modifications to the Zulip instance.

The default set of streams is chosen to allow incoming people to be able to have at least one place to go that can then, if necessary, direct them to a more specific location.

Currently that means that every top-level group present on Zulip is by default visible. Specifically, no stream that contains a / will be enabled by default.

Currently this set is:

• general
• t-lang
• t-compiler
• t-libs
• project-ffi-unwind
• project-inline-asm
• project-safe-transmute
• rust-survey-2019
• wg-async-foundations
• wg-database
• wg-formal-methods
• wg-secure-code
• wg-traits
• zulip

An alternative, minimalistic, approach is to use:

• general
• zulip
• announce
• new members

as the default set, which would push people into customizing their default set when starting out.

Stream naming

A stream should be named such as #t-{team}/{group name}. For example, #t-compiler/parallel-rustc. More levels of nesting are fine, e.g., a working group might want “subgroups” as well, though you may want to omit the team name in such a case – keeping the stream name short is good for usability, to avoid confusion between different streams which share the same prefix.

If no top-level team exists, or the group spans multiple teams (e.g., project-ffi-unwind), then the top level team should be omitted.

Streams should be clearly communicated as being for a specific purpose. That purpose can be broad, but it should likely include a group of some kind (even if that group is transient, e.g., people who are having trouble with the rust build system, or people working on the compiler). Furthermore, we do not currently intend for this Zulip to be a general place for community projects not affiliated with the Rust organization; if they wish to use Zulip, it is free for open source.

When a new stream is created, you should announce it in #announce. This is generally done automatically by Zulip.

Topics

A topic is attached to every message within a given stream (these are the subdivisions within streams). Topics are generally transient, and live for as long as there is active discussion on a topic. Thinking of topics like email subjects is helpful.

New conversation in a given stream should almost always start in a new topic, not a preexisting one. Unlike (for example) GitHub issues, you should not attempt to search for a past topic on the same subject. Do not spend too long on the name of the topic, either, beyond trying to make it short. Topics should generally be no longer than 20 characters (loosely two to three words), to make sure it is visible to users.

You should eagerly fork new discussion topics into fresh topics. Note that this can be done with the tail of another topic (if accidentally you diverge into another area of discussion).

To fork from an existing topic, see Zulip’s documentation here.

Messages

Zulip is a unique platform which combines synchronous and asynchronous communication in one location. You should not generally expect that your messages will receive a response quickly, and unlike (for example) Discord, there is likely not much reason to “re-ping” on a particular issue every few hours as your message is unlikely to vanish into history, being isolated to a specific topic.

Linkifiers

Our Zulip supports a lot of helpful linkifiers, and we’re generally happy to add more on request. See the documentation for the format. Propose one in #zulip!

Generally, github-org/repo#123 works for linking to an issue or PR; the below list gives a few more “special cased” repositories.

Don’t forget that standard Markdown syntax for links also works.

We support linking to issues on repositories inside the rust-lang GitHub organisation without requiring the rust-lang/ prefix. For example:

• rust-lang/rfcs with RFC#3434 or rfc#3434
• rust-lang/async-book with async-book#2334
• rust-lang/cargo with cargo#2334

rust-lang/rust issues can linked without needing any prefix:

• rust-lang/rust with #4545 or rust#4545

We currently support linking to commits on these repositories:

• rust-lang/rust with 40-character long SHAs, e.g., 25434f898b499876203a3b95c1b38bad5ed2cc5d

Read-only view

Our Zulip instance has the web-public streams beta feature enabled, and we use it for all public streams. Please let us or Zulip developers know if there’s any problems with this. The previous solution to the web-public view was the zulip archive, which now redirects to the web public view.

Zulip Moderation

Zulip, like all official Rust spaces, is governed by the Code of Conduct. If you have concerns, please feel free to escalate to the moderation team.

However, though the moderation team is the top-level body here, it is not the only place where you can seek help with moderation within Zulip.

One method for reaching the Zulip administrators privately is to email zulip-admin.239bd484c0347d2d43214d8581f3e125.show-sender@streams.zulipchat.com. See this page for details on how this works.

You can also ping the @mods group on Zulip; note that this will be public.

It is not currently possible for normal users to self-administrate (e.g., muting another user). However, each individual stream, including private streams, can be muted:

For admins/moderators

Some common actions for moderators are listed on this page.

Notably,

• in “Organization permissions” we can restrict users to mandate invitations before joining (this is the “no new users” button)

New admins/moderators should add themselves to the mods group on Zulip. (Note that this is something that any user can do!)

Rust Blog Guidelines

Context

The Rust project maintains two blogs. The “main blog” (blog.rust-lang.org) and a “inside Rust blog” (blog.rust-lang.org/inside-rust). This document provides the guidelines for what it takes to write a post for each of those blogs, as well as how to propose a post and to choose which blog is most appropriate.

How to select the right blog: audience

So you want to write a Rust blog post, and you’d like to know which blog you should post it on. Ultimately, there are three options:

• The main Rust blog
  • Suitable when your audience is “all Rust users or potential users”
  • Written from an “official position”, even if signed by an individual
• The inside Rust blog
  • Suitable when your audience is “all Rust contributors or potential contributors”
  • Written from an “official position”, even if signed by an individual
• Your own personal blog
  • Everything else

There are two key questions to answer in deciding which of these seems right:

• Are you speaking in an “official capacity” or as a “private citizen”?
• Who is the audience for your post?

In general, if you are speaking as a “private citizen”, then you are probably best off writing on your own personal blog.

If, however, you are writing in an official capacity, then one of the Rust blogs would be a good fit. Note that this doesn’t mean you can’t write as an individual. Plenty of the posts on Rust’s blog are signed by individuals, and, in fact, that is the preferred option. However, those posts are typically documenting the official position of a team — a good example is Aaron Turon’s classic post on Rust’s language ergonomics initiative. Sometimes, the posts are describing an exciting project, but again in a way that represents the project as a whole (e.g., Manish Goregaokar’s report on Fearless Concurrency in Firefox Quantum).

To decide between the main blog and the inside Rust blog, the question to ask yourself is who is the audience for your post. Posts on the main blog should be targeting all Rust users or potential users — they tend to be lighter on technical detail, and written without requiring as much context. Posts on the inside Rust blog can assume a lot more context and familiarity with Rust.

Writing for the Main Rust blog

The Leadership Council ultimately decides what to post on the main Rust blog.

Post proposals describing exciting developments from within the Rust org are welcome, as well as posts that describe exciting applications of Rust. We do not generally do “promotional cross-posting” with other projects, however.

Release note blog posts

One special case are the regular release note posts that accompany every Rust release. These are managed by the release team and go on the main blog.

The blog posts are published on the same day as the release by the same person in the release team running the release. Releases always happen on Thursdays.

Before publishing a release post, it goes through a drafting process:

1. The milestone (e.g. for 1.39.0) for the release is consulted.
2. PRs that we think are sufficiently important are included, and some items are headlined. The writing of a blog post typically happens through a hackmd document.
3. Headlined items are sometimes written by different people, and we try to peer-review each subsection.
4. The blog post draft is submitted as a PR on the blog repo for final review a few days before the release.

Inside Rust blogs

Teams can generally decide for themselves what to write on the inside Rust blog.

Typical subjects for inside Rust blog posts include:

• New initiatives and calls for participation
• Updates and status reports from ongoing work
• Design notes

Approval process

For both the inside Rust and main blogs, we require an approval from:

• Any team lead (top level or not)
• Any leadership council member
• Rust Foundation project director

These are primarily the members of the inside-rust-reviewers marker team¹. Note that this applies to both the main and inside Rust blogs (renaming will happen at some later point).

This approval should evaluate:

• Is the tone and content of the post appropriate for the official venue?
  • For example, we should avoid negative commentary about other ecosystems/languages.
• Is it clear on whose behalf the post is written?
  • This may not just be the by-line, but also the langauge used. If the post takes official positions on behalf of the Rust Project as a whole, please make sure at least one member of the leadership council signs off on it. If the post is taking positions on behalf of a team, then that team should be in agreement with the content.

In general, it’s a good idea to make sure someone (not necessarily the approver above) has proofread the post, but we generally prioritize unblocking posting over perfect content for the blog. Note that the above generally does NOT require that this person is a member of the team you’re posting on behalf, though they should be aware of the post.

Getting a review

Triagebot will automatically assign a leadership council representative to each new blog PR. That representative is who you should ping if you’re not getting a review promptly, but you may get a faster review from asking team lead(s) for their review as well. In other words, we recommend escalating to your team lead(s), then pinging your team’s leadership council representative, and finally the assigned reviewer.

The assigned reviewer is ultimately responsible for making sure a review happens.

Typically you should expect at least ~1 week of latency on initial review. Re-review for any final edits or a final merge button press can usually be promptly driven – find a member of the group above available when you need to merge the post.

1. Release team members are also included there for release blog purposes, but aren’t considered eligible approvers for any random post at this time. ↩

Calendars

Many Rust teams and working groups have regular meetings, and it can get challenging quickly to manage all the calendar events.

That’s why we have automation available for generating both one-time and recurring calendar events. It can be found in the calendar repository, which also contains a guide for its usage.

You can use it to create and update calendar invites declaratively using a TOML file, and the tool will then generate .ics files from them, which can be imported into various calendar tools.

Triagebot

Triagebot (AKA rustbot) is a general-purpose bot used for a wide variety of tasks in the rust-lang organization, usually involving sending commands via GitHub or Zulip comments. The following pages explain the available features.

Commands are usually issued by writing comments starting with the text @rustbot. The commands that are available depends on which repository you are using. Each repository has a triagebot.toml where you can see which features are enabled.

For example, the following comment:

@rustbot label A-diagnostics A-macros

will set the given labels on a GitHub issue or pull request, even for people who don’t have direct permissions to do that in the GitHub UI.

GitHub commands

Commands on GitHub issues or pull requests are usually issued by writing @rustbot followed by the command anywhere in the comment. @rustbot will ignore commands in markdown code blocks, inline code spans, HTML blocks, or blockquotes. Multiple rustbot commands can be entered in a single comment.

Triagebot also allows editing of a comment. If you don’t modify the text of the command, then triagebot will ignore the edit. However, if you modify an existing command, or add new ones, then those commands will be processed.

Configuration

Individual GitHub repositories can configure triagebot features via a file called triagebot.toml in the root of the default branch. The following pages explain the syntax needed for each feature.

For example, the rust-lang/rust configuration file is at https://github.com/rust-lang/rust/blob/master/triagebot.toml.

When first adding triagebot.toml to a new repository, you will need to enable permissions for the bot to operate. This can be done by posting a PR to the rust-lang/team database to add bots = ["rustbot"] to the repository in the repos/rust-lang directory.

Common command summary

The following are some common commands you may see on rust-lang/rust.

The following are some common commands you may see on Zulip:

Implementation

The source code for triagebot can be found at https://github.com/rust-lang/triagebot. If you are interested in extending triagebot, the documentation there should provide some guidance on how to get started.

Agenda Generator

The lang team uses the agenda generator to assist with meeting agendas.

Usage

The agenda generator can be viewed at https://triage.rust-lang.org/agenda.

Configuration

This feature has no configuration.

Implementation

See src/agenda.rs.

Issue Assignment

The issue assignment commands allows any user to assign themselves to a GitHub issue.

Usage

Issue assignment is done by entering one of these commands in a GitHub comment:

• @rustbot claim — Assigns the issue to yourself.
• @rustbot release-assignment — Removes the current assignee. Only the current assignee or a team member can release an assignment.
• @rustbot assign @user — Assigns a specific user. Only team members can assign other users.

Due to GitHub restrictions, not all users can be directly assigned to an issue. Only users with write permission to the repo, or rust-lang organization members can be directly assigned. If triagebot is unable to directly assign the user, it will instead assign @rustbot and edit the top-level comment with a message that the issue has been claimed.

Configuration

Issue assignment is enabled on a repository by the existence of the [assign] table in triagebot.toml:

[assign]

Implementation

See parser/src/command/assign.rs and src/handlers/assign.rs.

PR Assignment

Triagebot handles automatic and manual assignment of GitHub PRs. It also handles welcoming new users when they post a PR.

Rust contributors can track and manage their own work queue using the Zulipchat integration. See Tracking PR assignment.

Usage

Automatic assignment of new PRs is handled by the configuration in the triagebot.toml, described below.

Manual assignment can be done by posting a comment on the PR with the text:

• r? @octocat — Assigns a specific user.
• r? octocat — The @ is optional.
• r? libs — Chooses a random person from the libs ad-hoc group defined in triagebot.toml. For example, for the rust-lang/rust repository, see triagebot.toml for a list of ad-hoc group names.
• r? rust-lang/libs — The rust-lang/ org name prefix is optional.
• r? rustdoc — Chooses a random person from the rustdoc team. See the teams database for a list of team names.
• r? rust-lang/rustdoc — The org name prefix is optional. It is strongly recommended that you do not use @, as that will subscribe and notify the entire team to the PR.

When choosing a user from a team, triagebot only looks at direct team members (it ignores subteams).

When looking up a name, triagebot will first look at ad-hoc groups, then rust-lang teams, and if it doesn’t match either of those it assumes it is a GitHub user.

PRs can only be assigned to users with write permissions to the repo, any rust-lang org members with read permissions, or anyone who has commented on the PR.

To enable the ability for users to post a comment with r? name to set the assignment to a specific user, add a [assign] table to triagebot.toml.

Ghost

Using r? ghost in the initial PR top-level comment when opening a PR will disable triagebot’s auto-assignment. ghost is GitHub’s placeholder account for deleted accounts. It is used here for convenience. This is typically used for rollups or experiments where you don’t want any assignments or noise.

Configuration

PR assignment is enabled on the repository by having an [assign.owners] table in triagebot.toml:

# These are ad-hoc groups that can be referenced in `r?` and the `owners` table below.
# The values may contain GitHub usernames, other groups, or rust-lang teams.
# The `@` is optional.
# Group names should be lowercase.
[assign.adhoc_groups]
libs = ["@joshtriplett", "@Mark-Simulacrum", "@kenntytm", "@m-ou-se", "@thomcc"]
# Can reference other groups.
compiler = ["compiler-team", "compiler-team-contributors"]
compiler-team = ["cjgillot", "estebank"]
compiler-team-contributors = ["compiler-errors", "jackh726"]
# Can reference rust-lang teams.
libs = ["rust-lang/libs-api"]
# This is a special group that will be used if none of the `owners` entries matches.
fallback = ["@Mark-Simulacrum"]

# This specifies users, groups, or teams to assign for different paths.
# Triagebot will pick one person to assign.
# Paths are gitignore-style matches.
[assign.owners]
# Examples of assigning individuals.
"Cargo.lock" = ["@Mark-Simulacrum"]
"/library/std/src/sys/windows" = ["@ChrisDenton"]
# Example of assigning to a group.
"/library/std" = ["libs"]
# Supports gitignore patterns.
"*.js" = ["@octocat"]
# If you want to match all files, `*` should be sufficient.
"*" = ["@octocat"]
# Can use teams from the rust-lang teams database.
"/src/tools/cargo" = ["@rust-lang/cargo"]

If the owners map is configured, then triagebot will automatically select a reviewer based on which files were modified in the PR.

Vacation

If a reviewer wants to temporarily prevent themselves from being assigned (automatically or manually) they can add themselves to the special assign.users_on_vacation group.

[assign]
users_on_vacation = ["jyn514", "ChrisDenton"]

Additional new PR trigger options

Triagebot will also post a welcome message to the user. Its behavior depends on a few factors:

• PR authors who have not previously made any commits will get a more detailed welcome message.
• PR authors who have made commits will get an abbreviated message.
• If the initial PR comment has an r? command, then no welcome will be posted.

There are several options in triagebot.toml for controlling its behavior on new PRs:

[assign]
# If set, posts a warning message if the PR is opened against a non-default
# branch (usually main or master).
warn_non_default_branch = true
# If set, the welcome message to new contributors will include this link to
# a contributing guide.
contributing_url = "https://rustc-dev-guide.rust-lang.org/contributing.html"

Additionally, triagebot will post a comment with a warning if the PR modifies any submodules.

Exceptions to default branch warning

Some PRs may have a different default branch than the rest of the PRs, in these cases it is possible to add exceptions based on the PR title, which will therefore warn if the PR is targeting a different branch than specified.

[assign]
warn_non_default_branch.enable = true

[[assign.warn_non_default_branch.exceptions]]
title = "[beta" # title contains "[beta" in it
branch = "beta"

Implementation

See parser/src/command/assign.rs and src/handlers/assign.rs.

Tracking PR assignment

If you contribute in some capacity to the Rust compiler development, you might also be assigned pull requests to be reviewed.

You can check your current review assignment in two ways:

• by visiting this GitHub URL
• by interacting with the triagebot on the Zulip chat in a DM (Direct Messages) thread. You can open a direct message session with the triagebot clicking on this link (requires Zulip login).

This chapter will describe how to interact with the triagebot on Zulip.

Configuration

Tracking the PR assignment is enabled on the git repository by having a [pr-tracking] table in triagebot.toml. No additional configuration is needed.

Usage

Open a Direct Message session with the triagebot and send a message with one of these commands:

• work — Will emit an error and show the available commands
• work show — Will show your Github username and a list of pull requests assigned to you for review (on the rust-lang/rust git repository)

Implementation

See parser/src/handlers/pr_tracking.rs.

Autolabels

Auto labels will automatically apply labels to GitHub issues and PRs based on the [autolabel] configuration in triagebot.toml.

Usage

Auto labels have no manual control. See labeling for manually changing labels.

Configuration

Triggered by labels

Labels can be added when another label is added. The trigger_labels config option specifies which labels will cause this to trigger.

# Automatically applies the `I-prioritize` label whenever one of the labels
# listed below is added to an issue (unless the issue already has one of the
# labels listed in `exclude_labels`).
[autolabel."I-prioritize"]
trigger_labels = [
    "regression-untriaged",
    "regression-from-stable-to-stable",
    "regression-from-stable-to-beta",
    "regression-from-stable-to-nightly",
    "I-unsound",
]
exclude_labels = [
    "P-*",
    "T-infra",
    "T-release",
    "requires-nightly",
]

Exclude labels support shell-like * glob patterns.

Triggered by files

Labels can be added based on which files are modified in a PR. The trigger_files config option specifies which files will cause the label to be added. Paths are matched with starts_with.

# Adds the `T-compiler` label to any PR that touches `compiler` or
# `src/test/ui` unless it already has a `T-*` label.
[autolabel."T-compiler"]
trigger_files = [
    "compiler",
    "tests/ui",
]
exclude_labels = [
    "T-*",
]

Triggered by new PRs

Labels can be added to any PR when it is opened. Set the new_pr = true config option to enable this. For example:

[autolabel."S-waiting-on-review"]
new_pr = true

Triggered by new issues

Labels can be added to any issue when it is opened. Set the new_issue = true config option to enable this. For example:

[autolabel."new-issue"]
new_issue = true

Implementation

See src/handlers/autolabel.rs.

Behind Upstream

This handler checks if a PR is based on an X days old commit.

Context

When a PR’s code is based on a very old commit from an upstream branch: It passes when tested locally, but fails when the PR is submitted for testing through CI.

This is because the CI applies the commit patches to the current upstream branch, which may have new test cases, so it won’t pass. We need to rebase the PR to the nearest upstream branch.

Configuration

The default threshold is currently set at 7 days.

This feature is enabled on a repository by having a [behind-upstream] table in triagebot.toml:

[behind-upstream]

or, you can set the day threshold,

[behind-upstream]
days-threshold = 7

Implementation

See src/handlers/check_commits/behind_upstream.rs.

Canonicalize Issue Links

This handler was renamed to [issue-links] see Issue Links.

Close

The close command can be used to close a GitHub issue or pull request.

Usage

To close an issue or pull request, any rust-lang team member may enter the command:

@rustbot close

This will immediately close the issue or PR.

Configuration

This feature is enabled on a repository by having a [close] table in triagebot.toml:

[close]

Implementation

See src/handlers/close.rs and parser/src/command/close.rs.

Documentation Updates

Triagebot automatically generates a PR to rust-lang/rust every two weeks that updates all of the book submodules. This PR requires manual approval. These updates are currently managed by @ehuss.

Usage

There are no settings or manual controls for this feature.

Implementation

See src/handlers/docs_update.rs.

GitHub Releases

Triagebot can be used to automatically create releases on GitHub when a tag is pushed, using the relevant section of the changelog as the release body. No artifacts are uploaded when doing this.

Usage

Any time you push a git tag, or update the contents of the changelog, triagebot will synchronize all tags with the releases. That is, any tag that doesn’t have a release will create a new release. Additionally, the text of all the releases will be synchronized with the text in the changelog.

Tags that don’t have entries in the changelog will not create a release.

Configuration

To enable automatically creating GitHub Releases, add this to the triagebot.toml at the root of your repository:

[github-releases]
format = "rustc"
project-name = "Rust"
changelog-path = "RELEASES.md"
changelog-branch = "master"

The format defines which format the changelog file adheres to, and it’s used to properly extract the relevant section from it. You can add another format by changing triagebot’s src/changelogs/. The currently supported formats are:

• rustc: follows the custom style of rustc’s RELEASES.md.

The project-name defines what the title of the release should be. The final title will be {project-name} {tag}.

The changelog-path and changelog-branch keys define where triagebot should look at when searching for the changelog.

Implementation

See src/handlers/github_releases.rs and src/changelogs/.

Issue Links

Canonicalise Issue Links

GitHub permits having automatic action like Fixes #123, which closes the issue number 123. This handler updates the pull-request description with the canonicalized version, Fixes org/repo#123.

This is useful when updating subtrees into the upstream repository as it avoids referencing and closing the issue from the upstream repository instead of the one from the subtree.

Issue Links in Commits

GitHub also permits having having issue links in commits which are then referenced in the issue. While useful, they often more than anything else spam the referenced issue. This handler puts a warning against them.

Configuration

This feature is enabled on a repository by having a [issue-links] table in triagebot.toml:

[issue-links]

Without commits checking

[issue-links]
check-commits = false # defaults to true

Implementation

See src/handlers/issue_links.rs and src/handlers/check_commits/issue_links.rs.

Issue Transfer

The transfer command allows you to transfer a GitHub issue from one repository to another.

Usage

To transfer an issue to another repository, enter a comment with the form:

@rustbot transfer <repository-name>

It is recommended to also include a comment explaining why you are transferring. For example:

Transferring to rust-lang/cargo since this is an issue with how cargo
implements diagnostic reports.

@rustbot transfer cargo

IMPORTANT: There will be no visual indication that the issue is being transferred. Due to GitHub API limitations, you will not see any activity. You must reload the page to view the issue in its new location. It may take a few moments for GitHub to transfer all the data.

WARNING: Transferring is a partially destructive command. For example, labels and milestones that don’t exist in the target repository will be removed from the issue.

The transfer command is limited to team members of the rust-lang org, as well as members of wg-triage, wg-prioritization, and wg-async, and transfers can only happen to repositories in the rust-lang org. Also, the destination repository must have triagebot enabled on it.

Configuration

The source repository must have an empty transfer table to enable transfers from that repository. Issues can be transferred to any repository in the rust-lang org (that has triagebot enabled).

[transfer]

Implementation

See parser/src/command/transfer.rs and src/handlers/transfer.rs.

Labeling

You can apply GitHub labels to an issue or PR by posting a comment. Labeling of issues can be very helpful for searching, tying issues together, and indicating information in a formal way, such as the status.

The Triage WG helps with labeling issues. If you are interested in helping triaging issues, see the Triage WG procedure.

Usage

The general form of the comment should be @rustbot label followed by a space-separated list of labels to add or remove. You can remove labels by prefixing them with the - character. Some examples:

• @rustbot label A-diagnostics A-macros
• @rustbot label +T-lang -T-compiler — Removes T-compiler and adds T-lang.

The syntax for the command is somewhat flexible, supporting a few different forms to suit your pleasure. Some examples of variants you can use:

• @rustbot label: +T-lang, -T-compiler
• @rustbot label: +T-lang and -T-compiler
• @rustbot modify labels to +T-lang and -T-compiler
• @rustbot modify labels: +T-lang and -T-compiler
• @rustbot modify labels to +T-lang -T-compiler
• @rustbot labels "+good first issue"

The command can be terminated with a ., ;, or the end of the line.

Formally the grammar is:

Command → @rustbot modify? label-word to? :? label-list (; | .)?

label-word →
      label
   | labels

label-list →
      label-delta⁺
   | label-delta and label-list
   | label-delta , label-list
   | label-delta , and label-list

label-delta →
      + label
   | - label
   | label
   | " + label-quoted "
   | " - label-quoted "
   | " label-quoted "

label-quoted → [^“]*

label → [^.,:!?;\n() ]+

Permissions

All labels can be assigned by rust-lang organization team members (and wg-triage, wg-prioritization, and wg-async). Users not on a team can only assign labels that are explicitly authorized in triagebot.toml. It is encouraged for maintainers to allow the majority of labels to be applied by anyone. An example of one that would be restricted is beta-accepted, since accepting a backport to beta is usually only done by a team member.

Configuration

Labeling support is enabled on a repo by having a [relabel] table in triagebot.toml:

[relabel]

Permissions for allowing unauthenticated labeling is done by listing the labels in the allow-unauthenticated list:

[relabel]
# any label is allowed to be set by team members (anyone on a team in rust-lang/team)
# but these can be set by anyone in the world
allow-unauthenticated = [
    "C-*", # any C- prefixed label will be allowed for anyone, independent of authorization with rust-lang/team
    "!C-bug", # but not C-bug (order does not matter)
]

Implementation

See src/handlers/relabel.rs.

Major Changes

Triagebot helps with automated processing of Major Change Proposals.

Usage

The process starts when the appropriate label is set on an issue. For example, the rust-lang/compiler-team repo has a major change template which will automatically set the major-change label. Triagebot will detect this and create a new Zulip topic for hosting discussion, and post a comment to the issue with a link to Zulip stream.

If a team member writes a comment on the GitHub issue with @rustbot second (or @rustbot seconded), then triagebot will set the appropriate label, and post a comment to Zulip.

If a team member adds the major-change-accepted label, then triagebot will post a comment to Zulip to let people know that it has been accepted.

Configuration

This feature is enabled by the [major-change] table in triagebot.toml:

[major-change]
# Issues that have this label will start the MCP process.
# Defaults to "major-change".
enabling_label = "major-change"

# Label to apply once an MCP is seconded.
second_label = "final-comment-period"

# Label to apply when an MCP is created.
# Typically this is used to track what needs to be discussed at a meeting.
meeting_label = "to-announce"

# When this label is added to an issue, that triggers acceptance of the proposal
# which sends an update to Zulip.
# Defaults to "major-change-accepted".
accept_label = "major-change-accepted"

# Optional extra text that is included in the GitHub comment when the issue is opened.
open_extra_text = "cc @rust-lang/compiler @rust-lang/compiler-contributors"

# The Zulip stream to automatically create topics about MCPs in
# Can be found by looking for the first number in URLs, e.g.
# https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
zulip_stream = 233931

# An Zulip group or username to tag in the Zulip message when a
# proposal has been seconded.
zulip_ping = "T-compiler"

Implementation

See src/handlers/major_change.rs.

Mentions

Triagebot can leave a comment on PRs that touch certain files. This can be useful to alert people who want to review any change to those files, or to provide a informational message to the author.

Usage

Mentions are triggered automatically when a PR is opened (or new changes are pushed) based on the configuration in triagebot.toml of the repo.

Configuration

To enable mentions, add entries to the [mentions] table in triagebot.toml. Each key in the table should be a path in the repo. Triagebot will check for modifications to any file that starts with the given path. For example, library/std would match anything under the library/std directory like library/std/src/process.rs.

There are two optional values that can be specified in the table:

• cc — A list of strings of users to ping. They should start with @ like @ehuss or @rust-lang/clippy. If this is not specified, nobody will be pinged.
• message — This is the message that will be included in the comment. If this is not specified, the comment will say Some changes occurred in {path}.

Example:

[mentions."src/tools/cargo"]
cc = ["@ehuss"]

[mentions."src/rustdoc-json-types"]
message = """
rustdoc-json-types is a **public** (although nightly-only) API.
If possible, consider changing `src/librustdoc/json/conversions.rs`;
otherwise, make sure you bump the `FORMAT_VERSION` constant.
"""

Implementation

See parser/src/mentions.rs and src/handlers/mentions.rs

Merge Conflicts

The merge-conflicts feature detects if a Pull Request has a merge conflict, and will post a comment asking the author to resolve the conflicts.

Usage

This is triggered automatically when a commit is made to a branch that causes existing, open PRs to have a merge conflict. The bot will post a comment to the PR that roughly looks like this:

☔ The latest upstream changes (possibly #152) made this pull request unmergeable. Please resolve the merge conflicts.

Note that it may take a minute or so for the comments to be posted.

Configuration

This feature is enabled on a repository by having a [merge-conflicts] table in triagebot.toml:

[merge-conflicts]

There are several optional keys that you can include:

• remove — A list of labels to remove from the PR when a conflict is detected.
• add — A list of labels to add to the PR when a conflict is detected.
• unless — A list of labels that, if already present on the PR, will prevent triagebot from adding or removing labels.

Example

[merge-conflicts]
remove = ['S-waiting-on-bors']
add = ['S-waiting-on-author']
unless = ['S-blocked', 'S-waiting-on-crater', 'S-waiting-on-team', 'S-waiting-on-review']

Implementation

See src/handlers/merge_conflicts.rs.

No Merge Policy

The no-merge policy informs users if they have merge commits in their pull request. Some repositories prefer to only use a rebase-oriented workflow.

Usage

This is triggered automatically if a PR has merge commits. Triagebot will post a comment on the PR if it detects merge commits. The comment will explain the no-merge policy, and how the user can avoid merge commits.

Configuration

This feature is enabled on a repository by having a [no-merges] table in triagebot.toml:

[no-merges]

There are three optional values that can be specified in the table:

• exclude_titles — A list of strings of title segments to exclude. PRs with titles containing these substrings will not be checked for merge commits. Case sensitive.

• labels — A list of strings of label names to add. These labels will be set on the PR when merge commits are detected.

• message — Override the default message posted for merge commits. The message will always be followed up with “The following commits are merge commits:” and then a list of the merge commits.

Default message

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git pull --rebase https://github.com/rust-lang/rust.git master
$ git push --force-with-lease

Example

[no-merges]
# PRs with the following labels will be skipped 
exclude_labels = ["rollup", "sync"]
# Add the following labels to PRs with merge commits
labels = ["has-merge-commits", "S-waiting-on-author"]
# Post the following warning message as a comment on PRs with merge commits
message = """
This repository does not allow merge commits.
Your PR cannot be merged until it is rebased.
"""

Implementation

See src/handlers/no_merges.rs.

No Mentions (in commits)

GitHub permits having mentions (eg. @user) in commits, and while it’s sometimes useful it almost always ends-up spamming the mentioned users, in particular as the commits are being rebased, cherry-picked or pushed.

This handler tries to prevent those mentions by adding a comment warning in the PR against them.

Configuration

This feature is enabled on a repository by having a [no-mentions] table in triagebot.toml:

[no-mentions]

Implementation

See src/handlers/check_commits/no_mentions.rs.

Nominate

The nominate commands are used for nominating issues for backporting.

Usage

There are multiple commands that can be issued in a GitHub comment to handle nomination:

• @rustbot beta-nominate <team> — Adds the beta-nominated and the given team’s label. This indicates that the issue is nominated for beta backport, and the team should decide whether to accept or reject it.
• @rustbot nominate <team> — Adds the I-nominated and the given team’s label. This is used to nominate an issue for the team to discuss.
• @rustbot beta-accept — Adds the beta-accepted label. This indicates that it has been approved for beta backport, and someone (usually the release team) will take care of applying the backport.
  • @rustbot beta-approve — An alias for beta-accept.

Only rust-lang team members may use the nominate commands.

Only teams that are listed in the configuration can be nominated.

If you need to nominate multiple teams, add each one in a separate command. This is to encourage descriptions of what to do targeted at each team, rather than a general summary.

Configuration

This feature is enabled on a repository by having a [nominate] table in triagebot.toml. The nominate.teams table lists the team names, and the associated labels that should be used for that team.

[nominate.teams]
compiler = "T-compiler"
release = "T-release"
core = "T-core"
infra = "T-infra"

Implementation

See src/handlers/nominate.rs and parser/src/command/nominate.rs.

Note

The note command can be used to update the top comment of a GitHub issue with a summary.

Usage

A summary note can be added to a GitHub issue by writing a comment with the command:

@rustbot note summary-title

The word after note is then added as a link to the top comment of the GitHub issue:

<!-- TRIAGEBOT_SUMMARY_START -->

### Summary Notes

- ["summary-title" by @username](link-to-comment)

Generated by triagebot, see [help](https://github.com/rust-lang/triagebot/wiki/Note) for how to add more
<!-- TRIAGEBOT_SUMMARY_END -->

with a link to the comment where you posted the note command.

The title word can be a sequence of characters matching the regular expression [^.,:!?;\n() ]+. Or it can be a quoted string like "this is a title".

Additional notes will get appended to the list:

<!-- TRIAGEBOT_SUMMARY_START -->

### Summary Notes

- ["first-note" by @username](link-to-comment)
- ["second-note" by @username](link-to-comment)
- ["summary-title" by @username](link-to-comment)

<!-- TRIAGEBOT_SUMMARY_END -->

This summary section should not be edited by hand.

Removing an existing summary

Notes can be removed by writing a comment with @rustbot note remove summary-title, where summary-title is the word used when the note was created. Triagebot will remove the entry from the summary list.

Configuration

This feature is enabled by having a [note] table in triagebot.toml:

[note]

Implementation

See parser/src/command/note.rs and src/handlers/note.rs.

Notifications

The notifications system helps a user keep track of GitHub notifications.

Usage

Each registered team member has a notifications page at:

https://triage.rust-lang.org/notifications?user=<github-username>

Whenever you are mentioned on GitHub with a direct mention (@user) or via a team mention (@rust-lang/libs) anywhere in the rust-lang organization, this will add an entry to the notifications list.

The notifications list can also be edited via Zulip by private-messaging triagebot. Any Rust organization member can edit their notifications page, or pages of other Rust organization team members. To do so, the editor must have a zulip-id listed in their people/username.toml file in the team repository. The bot will tell you which ID to use when talking to it for the first time; please r? @Mark-Simulacrum on PRs adding Zulip IDs.

The following commands are supported:

• acknowledge <url> (or short form ack <url>)
• acknowledge <idx> (or short form ack <idx>)

These both acknowledge (and remove) a notification from the list.

• acknowledge all or acknowledge * (or short form ack all or ack *)

This acknowledges and removes all notifications.

• add <url> <description... (multiple words)>

This adds a new notification to the list.

• move <from> <to>

This moves the notification at index from to the index to.

• meta <idx> <metadata...>

This adds some text as a sub-bullet to the notification at idx. If the metadata is empty, the text is removed.

• as <github username> <command...>

This executes any of the above commands as if you were the other GitHub user.

Configuration

There is no configuration for this feature.

Implementation

See src/handlers/notification.rs, src/notification_listing.rs, and src/db/notifications.rs.

Pinging

Triagebot can be used to “ping” teams of people that do not have corresponding GitHub teams. This is useful because sometimes we want to keep groups of people that we can notify but we don’t want to add all the members in those groups to the GitHub org, as that would imply that they are members of the Rust team (for example, GitHub would decorate their names with “member” and so forth). The compiler team uses this feature to reach the notification groups.

When a team is pinged, we will both post a message to the issue and add a label. The message will include a cc line that @-mentions all members of the team.

Usage

On repositories with a ping group configured, any Rust team member (and wg-triage, wg-prioritization, and wg-async) can write a GitHub comment such as:

@rustbot ping windows

which would cause triagebot to post a comment notifying the members of the windows ping group.

Teams that can be pinged

To be pinged, teams have to be created in the Rust team repository. Frequently those teams will be marked as marker-team, meaning that they do not appear on the website. The Icebreakers LLVM team is an example.

Additionally, the team needs to be configured in the repository’s triagebot.toml file.

Configuration

To enable the team (e.g. TeamName) to be pinged, you have to add section to the triagebot.toml file at the root of a repository, like so:

[ping.TeamName]
message = """\
Put your message here. It will be added as a Github comment,
so it can include Markdown and other markup.
"""
label = "help wanted"

This configuration would post the given message and also add the label help wanted to the issue.

You can also define aliases to add additional labels to refer to same target team. Aliases can be useful to add mnemonic labels or accommodate slight misspellings (such as “llvms” instead “llvm”), see the following example:

[ping.cleanup-crew]
alias = ["cleanup", "cleanups", "shrink", "reduce", "bisect"]
message = """\
message content...
"""

This will allow the command @rustbot ping cleanup-crew to be understood with all the aliased variants, ex.:

@rustbot ping cleanup
@rustbot ping shrink
...

Check out the rust-lang/rust configuration for an up-to-date examples.

Implementation

See parser/src/command/ping.rs and src/handlers/ping.rs.

Rendered link

Rendered links are simple hyperlinks that are automatically added (and updated) to a PR description by triagebot.

Configuration

This feature is enabled on a repository by having a [rendered-link] table in triagebot.toml:

[rendered-link]
trigger-files = ["posts/"]

The trigger-files key configures which directories are watched for modification, with the “Rendered link” pointing to the first file matching.

Implementation

See src/handlers/rendered_link.rs.

Requesting Prioritization

Users can request an issue to be prioritized by the Prioritization WG.

Usage

On repositories configured for prioritization, any user can post a comment with:

@rustbot prioritize

which will add the I-prioritize label to the issue to notify the Prioritization WG that the issue needs prioritization.

Configuration

This feature is enabled on a repository by the [prioritize] table in triagebot.toml:

[prioritize]
# Name of the label used for requesting prioritization on issues
label = "I-prioritize"

Implementation

See parser/src/command/prioritize.rs and src/handlers/prioritize.rs.

Review Changes Requested

This feature will automatically adjust the labels on a pull request when a reviewer sends a review with changes requested.

Usage

When creating a pull request review, click the “Request Changes” option when finishing the review. This will automatically remove the review labels, and add a new label to indicate that the PR is waiting on the author.

Configuration

This feature is enabled on a repository by having a [review-submitted] table in triagebot.toml:

[review-submitted]
# These labels are removed when a review is submitted.
review_labels = ["S-waiting-on-review"]
# This label is added when a review is submitted.
reviewed_label = "S-waiting-on-author"

Implementation

See src/handlers/review_submitted.rs.

Review Requested

This feature will automatically adjust the labels on a pull request when the PR author requests a review from an assignee.

Usage

In the list of reviewers, click the “Re-request review” button near an assignee’s name. This will automatically remove the “waiting on the author” labels, and add a new labels to indicate that the PR is waiting on the review.

Configuration

This feature is enabled on a repository by having a [review-requested] table in triagebot.toml:

[review-requested]
# Those labels are removed when PR author requests a review from an assignee
remove_labels = ["S-waiting-on-author"]
# Those labels are added when PR author requests a review from an assignee
add_labels = ["S-waiting-on-review"]

Implementation

See src/handlers/review_requested.rs.

Rustc Commit Tracking

Triagebot keeps a database of commits to the rust-lang/rust repository. This is useful since the GitHub API for fetching this information can be slow. For example, this is used by the rustc-perf system.

Usage

The top-level bors merge commits can be fetched from https://triage.rust-lang.org/bors-commit-list.

Configuration

This has no configuration, it is processed automatically.

Implementation

See src/db/rustc_commits.rs and src/handlers/rustc_commits.rs.

Shortcuts

Shortcuts are simple commands for performing common tasks.

Usage

Shortcut commands can be issued by writing a GitHub comment as indicated below.

ready

@rustbot ready

This indicates that a PR is ready for review. This assigns the S-waiting-on-review label on the pull request and removes both S-waiting-on-author and S-blocked if present.

@rustbot review or @rustbot reviewer are aliases for ready.

author

@rustbot author

This indicates that a PR is waiting on the author. This assigns the S-waiting-on-author label on the pull request and removes both S-waiting-on-review and S-blocked if present.

blocked

@rustbot blocked

This indicates that a PR is blocked on something. This assigns the S-blocked label on the pull request and removes both S-waiting-on-author and S-waiting-on-review if present.

Configuration

This feature is enabled on a repository by having a [shortcut] table in triagebot.toml:

[shortcut]

Implementation

See parser/src/command/shortcut.rs and src/handlers/shortcut.rs.

Triagebot Dashboard

The triage dashboard is used to assist with triaging open pull requests.

Usage

The triage dashboard for repositories can be found at https://triage.rust-lang.org/triage.

Any rust-lang repository can be viewed with the form https://triage.rust-lang.org/triage/<owner>/<repo>.

Configuration

This feature has no configuration.

Implementation

See src/triage.rs.

Zulip Meeting Management

Triagebot can respond to some commands in Zulip to assist with running a meeting.

Usage

Enter a message in Zulip addressed to @triagebot with a command listed below.

Document reading

@triagebot read

This command will cause triagebot to post a comment to poll when everyone is finished reading some document, and are ready to start discussing it. The message looks something like:

Click on the :book: when you start reading (and leave it clicked).
Click on the :checkered_flag: when you finish reading.

Users can then click the emoji reaction buttons to indicate that they are currently reading, and then again when they are finished.

End topic

@triagebot end-topic

This command will cause triagebot to post a comment to poll if everyone in the meeting is ready to move on to the next topic. The message looks something like:

Does anyone have something to add on the current topic?
React with :working_on_it: if you have something to say.
React with :all_good: if not.

Users can then click the emoji reaction buttons to indicate if they are ready or not.

@triagebot await is an alias for end-topic.

End meeting

@triagebot end-meeting

This command will cause triagebot to post a comment to poll if everyone is ready to end the meeting. The message looks something like:

Does anyone have something to bring up?
React with :working_on_it: if you have something to say.
React with :all_good: if you're ready to end the meeting.

Users can then click the emoji reaction buttons to indicate if they are ready to end or not.

Configuration

This feature has no configuration, it is available to all team members. Note that your Zulip ID needs to be configured in the teams database.

Implementation

See src/zulip.rs.

Zulip Notifications

Triagebot can send messages to Zulip based on various triggers like issue labels.

Usage

Zulip notifications are automated based on the configuration described below. They can be triggered based on the addition or removal of labels, or when an issue is closed or reopened.

For example, the rust-lang/rust repository is configured to automatically post a message whenever an issue is tagged with the A-edition-2021 label to the “Edition 2021” stream, which looks something like:

triagebot

Issue #109298 “ICE Subslice unexpected because it isn't captured –edition=2021” has been added.

Configuration

This feature is enabled on a repository by having a [notify-zulip] table in triagebot.toml:

# Triggers a Zulip notification based on the given label name.
[notify-zulip."label-name"]
# The Zulip stream to post to.
# Can be found by looking for the first number in URLs, e.g. https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
zulip_stream = 245100 # #t-compiler/prioritization/alerts

# The Zulip topic to post to.
# {number} is replaced with the issue/PR number.
# {title} is replaced with the issue/PR title.
topic = "#{number} {title}"

# The message to post when the label is added.
# Supports {number} and {title} substitution.
message_on_add = "Issue #{number} \"{title}\" has been added."

# The message to post when the label is removed.
# Supports {number} and {title} substitution.
message_on_remove = "Issue #{number}'s nomination has been removed. Thanks all for participating!"

# The message to post when the issue/PR is closed and it has the label.
# Supports {number} and {title} substitution.
message_on_close = "Issue #{number} has been closed. Thanks for participating!"

# The message to post when the issue/PR is reopened and it has the label.
# Supports {number} and {title} substitution.
message_on_reopen = "Issue #{number} has been reopened. Pinging @*T-types*."

# The Zulip notification will not be posted unless the issue/PR has all of these labels.
# Please replace the `{team}` placeholder with the appropriate team to be notified for the nomination
# (ex. `I-compiler-nominated`, `I-lang-nominated`, ...)
required_labels = ["I-{team}-nominated"]

Implementation

See src/handlers/notify_zulip.rs.

GitHub Actions created PR open/closer

This automation triggers an automatic close & reopen on PRs opened by the github-actions user, i.e., from a GitHub actions job. This enables CI to run on those PRs without needing a manual poke from some human.

Configuration

This feature is enabled on a repository by having a [bot-pull-requests] table in triagebot.toml:

[bot-pull-requests]

Implementation

See src/handlers/bot_pull_requests.rs.

Community

This section documents the processes of the community team, and related projects.

External Links

• The Community team GitHub repository contains information about how the community team organizes.
• The RustBridge website contains information on hosting your own local RustBridge event.
• Rustlings is an project with small exercises designed around getting newcomers used to reading and writing Rust.
• The State of Rust is an annual community survey gathering insights and feedbacks from Rust users, and all those who are interested in the future of Rust more generally.

Compiler

Rust’s compiler team are responsible for maintaining the Rust compiler, improving its performance and considering the stabilization of compiler features.

We use the Forge to document the team’s processes, policies and working practices, if you’d like to read about how the compiler works and instructions on how to set up a development environment, you’re looking for the rustc-dev-guide.

• Calendar
  • How do I subscribe to the compiler team’s calendar?
• Cross-team Collaboration
  • How do I request the help of the compiler team?
• Meetings
  • What meetings do the compiler team run and how can I attend?
• Membership
  • What is expected of compiler team members and how do I join?
• Resources
  • What useful resources are available for contributors and team members?
• Review Policy
  • How do I make a contribution which is easy to review? How do I start reviewing as a team member?
• Proposals, Approval and Stabilization
  • How do I propose a change to the compiler team? What approval is necessary for my change?
• Third-party and Out-of-tree Crates Policy
  • When can I add third-party crates to the compiler? When can I create a out-of-tree crate for the compiler?
• Triage and Prioritization
  • How are compiler issues triaged and prioritized?
• Working Areas
  • Specific areas of work around the compiler
• Repository we maintain
  • Various code repositories maintained by the Compiler Team
• Operations
  • Supporting the compiler team

Calendar

All of the compiler team’s calendars are available in the Rust project’s rust-lang/calendar repository.

Adding new events

Any project member can submit a pull request to add new events or subcalendars, just assign the compiler team’s leads as a reviewer for the pull request.

Subscribing to the calendar

The team’s calendar is distributed as an ics file that can be imported into your preferred calendar application.

You can copy the calendar link from below:

https://rust-lang.github.io/calendar/compiler.ics

Alternative links which do not include working groups are available on the calendar repository.

• Fastmail
  • Open the Settings page. Go to “Calendars” on the left sidebar. Scroll down to the “Subscriptions” section and paste the link to the compiler team calendar into the field and press “Subscribe to calendar”.
• Google Calendar
  • Press the “+” icon next to “Other Calendars” in the left sidebar. Select “From URL” and paste the link to the compiler team calendar into the field and press “Add calendar”.
• Outlook Web
  • Go to the Calendar using the icon on the left sidebar. Select “Add Calendar” on the left and then “Subscribe from the web”, paste the link to the compiler team calendar into the field and press “Import”.

If your preferred calendar application isn’t listed above, feel free to submit a pull request to this documentation to add instructions above.

Cross-team Collaboration

If you are a member of another team and would like to raise an issue with the compiler team..

..for discussion

Write a comment on a GitHub issue describing the reason for the nomination (i.e. what decision needs to be made/what opinion is sought; what are the relevant parts to the compiler team, etc) and add the I-compiler-nominated label to a issue (you can include @rustbot label +I-compiler-nominated in your comment to do this).

Once nominated, the issue will be discussed in a upcoming triage meeting. The compiler team doesn’t always get through all nominated issues each week, so it can take more than one meeting for your issue to be discussed.

Once discussed, a member of the team will comment on the issue with the conclusion of the discussion and linking to the relevant Zulip chat.

..to be fixed

If there is an existing working relationship between a member of the requesting team and a contributor to the compiler, then the first option that a team has for requesting tasks be completed is to ping that contributor and ask if they can complete the task. It is recommended that pings take place in public Zulip channels so that..

• ..other contributors that have free time have the opportunity to offer their help.
• ..other compiler team members/leadership can ensure that requests being made are reasonable (see the rest of this section for the types of issues that the compiler team commits to prioritizing on behalf of other teams).

It is worth considering the available bandwidth of the contributor that the request is being made of, and whether their areas of expertise in the compiler are relevant.

When there is not a appropriate contact in the compiler team to reach out to directly, write a comment on a GitHub issue (or create an issue) describing the task that needs completed. Teams should nominate issues for the compiler team when issues..

• ..are not already tracked by/part of an existing initiative or working group and..
• ..are blocking/impeding the work of the other team (e.g. a feature or bug preventing the stabilization of something otherwise complete), but..
• ..aren’t absolutely mission-critical - a soundness bug or otherwise critical issue will be prioritized by the prioritization working group and addressed through the compiler team’s other processes for these bugs. If the issue lacks a prioritization label, you can add the I-prioritize label and it will be enqueued for prioritization.

A detailed description of the feature being requested or the bug to be fixed is helpful wherever possible (so that the compiler contributor does not need to make a guess as to a solution that would solve the problem for the requesting team). If a member of the requesting team isn’t explicitly listed as the point-of-contact for the issue, then the author of the comment will be assumed to be the point-of-contact.

Add the I-compiler-nominated label to a issue (you can use @rustbot label +I-compiler-nominated to do this).

Once nominated, the issue will be discussed in a upcoming triage meeting. The compiler team doesn’t always get through all nominated issues each week, so it can take more than one meeting for your issue to be discussed. In the compiler team’s discussion, the issue may..

• ..be accepted, in which case it will be assigned to a contributor and the nomination label removed. Once assigned, a member of the team will work on the issue. If no work is completed after a reasonable time, then re-nominate the issue and the compiler team will find someone else to complete the work.
• ..or not accepted (e.g. due to insufficient bandwidth, other critical/high-priority bugs, being unable to find an appropriate contributor, or the issue lacking feasibility). In this case, the compiler team will reply to the nomination with an explanation and will remove the nomination label.

Meetings

The compiler team host various regular meetings to keep on top of regular business necessary for the running of the team and delivery of a high-quality compiler toolchain.

Triage Meeting

The weekly triage meeting takes place on Zulip: considering any backports, reviewing performance triage reports and discussing nominated issues. Triage meetings are held in the #t-compiler/meetings on Zulip. You can find the up-to-date meeting times in the team calendar. Anyone can attend and it is recommended that compiler team members do.

Agendas of triage meetings are stored on HackMD.

Generating the triage meeting agenda

See Prioritization for documentation on generating the triage meeting agenda.

Steering/Planning Meeting

The weekly steering/planning meeting also takes place on Zulip and is intended to host high-level discussions. Steering/planning meetings operate on a repeating schedule:

• Week 1: Planning meeting
  • Select the topics for the next three meetings from the team’s proposed meetings.
• Week 2-4: Steering meeting
  • Discuss the planned topic.

During planning meetings, the team lead running the meeting will attempt to identify topics which are relevant for discussion. Some topics may require more investigation before a discussion or may be out-of-date or more relevant to another team. Depending on the availabilities of the meeting proposer and relevant team members, the meetings will then be scheduled into the steering meeting slots of the following weeks. Not all meeting slots need to be scheduled.

Meetings are proposed by opening issues on the compiler team’s repository using the “meeting proposal” template. Steering meetings are good opportunities to discuss issues with the wider team that require a decision/vibe check and would take longer than is typically available when discussing nominated issues in a triage meeting.

It is expected that the proposer of a steering meeting prepare a short and informal document describing the topic and including all necessary context for the discussion, but this does not need to be prepared until the day of the meeting, it is not necessary for the initial meeting proposal.

Any contributor can propose a meeting topic. Some examples of good steering meeting topics include:

• Proposals which require feedback from the team
  • i.e. to refactor subsystems of the compiler or create new out-of-tree dependencies
• In-depth review of large contributions
  • i.e. the author describing and answering questions about their work
• Coordination between the team and the rest of the project
  • i.e. reviewing proposed project goals
• Deciding on a policy for the team
  • i.e. how to handle blockers from external dependencies

Scheduled planning and steering meetings can be found on the compiler team’s calendar.

Minutes of steering meetings are stored on HackMD.

Membership

This team discusses membership in the compiler team. There are currently two levels of membership:

• members: regular contributors with r+ rights, bot privileges, and access to infrastructure
• maintainers: members who have committed themselves to invest in the quality of the compiler and health of the compiler team

The path to membership

People who are looking to contribute to the compiler typically start in one of two ways. They may tackle “one off” issues, or they may get involved in some kind of existing working group. They don’t know much about the compiler yet and have no particular privileges. They are assigned to issues using the triagebot and (typically) work with a mentor or mentoring instructions.

Compiler team member

Once an individual has been contributing regularly for some time, they can be promoted to the level of a compiler team member (see the section on how decisions are made below). This title indicates that they are someone who contributes regularly.

It is hard to define the precise conditions when such a promotion is appropriate. Being promoted to member is not just a function of checking various boxes. But the general sense is that someone is ready when they have demonstrated three things:

• “Staying power” – the person should be contributing on a regular basis in some way. This might for example mean that they have completed a few projects.
• “Independence and familiarity” – they should be acting somewhat independently when taking on tasks, at least within the scope of the working group. They should plausibly be able to mentor others on simple PRs.
• “Cordiality” – compiler team members will be part of the Rust organization and are held to a higher standard with respect to the Code of Conduct. They should not only obey the letter of the CoC but also its spirit.

Being promoted to member implies a number of privileges:

• Members have r+ (approve a pull request) privileges and can do reviews (they are expected to use those powers appropriately, as discussed previously). They also have access to control perf/rustc-timer and other similar bots. See the documentation for bors and r+ here.

  Tip: some baseline rules around bors permissions are: don’t do a try build unless you have done a check for malicious code first and don’t r+ unless you are reasonably confident that you can effectively review the code in question.

• Compiler team members are members of the Rust organization so they can modify labels and be assigned to issues.

• Members become a part of the rust-lang/compiler team on GitHub, so that they receive pings when people are looking to address the team as a whole.

• Members are listed on the rust-lang.org web page.

It also implies some obligations (in some cases, optional obligations):

• Members will be asked if they wish to be added to the reviewer rotation.
• Members may take part in various other [maintainer activities] to help the team.
• Members are held to a higher standard than ordinary folk when it comes to the Code of Conduct.

What it means to be a compiler member

Once you’re a member of the compiler team, a number of events will happen:

• You will gain access to a private Zulip stream, where internal discussions happen or ideas in very draft state are shared. Come and say hello to your new team members!

• You will be subscribed and gain write access to a number of Github repositories. Check this GitHub page to see which repositories you have now access to. Some of them are pretty quiet or obsolete, so don’t worry about all of them.

  Tip: Github automatically adds you as subscriber to every repo you get write permission too. You can disable this in the settings (here).

• You will also be subscribed to the all@rust-lang.org mailing list. See this file to check how subscriptions to mailing lists work. It’s a very low-volume mailing list (maybe a few emails per year), it’s a way to communicate things to all contributors. We will not send you spam from this address.

Maintainers

After being a compiler team member for a year, members can request or be asked to become a compiler team maintainer. This implies that they are not only a regular contributor, but are actively helping to shape the direction of the team or some part of the compiler (or multiple parts).

• Compiler team maintainers are expected to participate in at least one [maintenance activities].
• Compiler team maintainers are identified with the “Maintainer” role on the rust-lang website.

How promotion decisions are made

After an individual has been contributing to the compiler for a while, they may be nominated by an existing compiler team member or they may ask the compiler team leads if their contribution history is sufficient for team membership.

The compiler team leads will check with the rest of the compiler team to see if there are concerns with extending a membership invitation to the individual and after a week (barring no objections), an invitation will be extended.

If the invitation is accepted by the individual, the compiler team leads will update the team repository to reflect their new role.

Not just code

It is worth emphasizing that becoming a member of the compiler team does not necessarily imply writing PRs. There are a wide variety of tasks that need to be done to support the compiler and which should make one eligible for membership. Such tasks would include organizing meetings, participating in meetings, bisecting and triaging issues, writing documentation, working on the rustc-dev-guide.

It is worth emphasizing that becoming a member of the compiler team does not necessarily imply writing PRs. There are a wide variety of tasks that need to be done to support the compiler and which should make one eligible for membership. Such tasks would include organizing meetings, participating in meetings, bisecting and triaging issues, writing documentation, working on the rustc-dev-guide. The most important criterion for elevation to compiler team member, in particular, is regular and consistent participation. The most important criterion for elevation to maintainer is actively shaping the direction of the team or compiler.

Alumni status

If at any time a compiler team member or maintainer wishes to take a break from participating, they can opt to put themselves into alumni status. When in alumni status, they will be removed from GitHub aliases and the like, so that they need not be bothered with pings and messages. They will also not have r+ privileges. Alumni members will however still remain members of the GitHub org overall.

People in alumni status can ask to return to “active” status at any time. This request would ordinarily be granted automatically barring extraordinary circumstances.

People in alumni status are still members of the team at the level they previously attained and they may publicly indicate that, though they should indicate the time period for which they were active as well.

Entering or leaving the Maintainer role

After a compiler team member has committed to actively maintaining the compiler by becoming a Maintainer, they may wish to take a break from these ongoing responsibilities either temporarily or indefinitely. In either case, the Maintainer can let the compiler team leads know or open a PR themselves to the team repo, removing themselves from the Maintainer marker team and placing themselves in the alumni list.

In the future, if the former Maintainer would like to resume maintenance duties, they can request re-instatement from the compiler team leads. This request would ordinarily be granted automatically barring extraordinary circumstances.

Compiler team alumni

Likewise, if any member of the compiler team would like to take an extended break from contribution and interaction with the team, they can let the compiler team leads know or open a PR themselves to the team repo, moving themselves to alumni status.

If an alumni member would like to resume compiler team membership in the future, they can request re-instatement from the compiler team leads and this will normally be granted.

Automatic alumni status after 6 months of inactivity

If a member or maintainer has been inactive in the compiler for 6 months, then we will ask them if they would like to go to alumni status. If they respond yes or do not respond, they can be placed on alumni status. If they would prefer to remain active, that is also fine, but they will get asked again periodically if they continue to be inactive.

Process: Adding a new team member

When a potential team member has been nominated by existing members, there is a standard process that can be followed by team leads to add the new team member:

1. Contact the nominees asking if they are interested in joining the team:

Hey $name, you've been nominated for compiler team membership by a few people on the compiler
team! The [compiler team re-org RFC][rfc] has the full details as to what this means. This would
grant you permission to resources like bors and such.

This would not require you to take on additional work or responsibilities (though joining the
review queue is encouraged), and is just public recognition of the great work you've already been
doing around the compiler!

If you would like to accept, please let me know and I can update the teams repo accordingly.

[rfc]: https://rust-lang.github.io/rfcs/3599-compiler-team-reorganisation.html#team-members

2. Add the new nominee to the teams repository and to the compiler team. This will sync with Zulip, GitHub, etc. to give the new team member access and permissions.

3. Draft a Inside Rust blog post introducing the new team members. See previous examples for a template.

Notification groups

The compiler team has a number of notification groups that used to ping people and draw their attention to issues. Notification groups are setup so that anyone can join them if they want.

Please keep in mind that only members of a Rust project GitHub team can use these notification groups. Non-team members will trigger an error from our automation bot.

Creating a notification group

If you’d like to create a notification group, here are the steps. First, you want to get approval from the compiler team:

• File a tracking issue in the rust-lang/compiler-team repository to collect your progress.
• Create a PR against the rust-lang/team repository adding the notification group (Example PR)
• Configure the rust-lang/rust repository to accept triagebot commands for this group. (Example PR.)))
• Create a PR for the rustc-dev-guide amending the notification group section to mention your group.
• Create a sample PR for the rust-lang/team repository showing how one can add oneself. This will be referenced by your blog post to show people how to join. (Example PR)
• Write an announcement blog post for Inside Rust and open a PR against blog.rust-lang.org. (Example PR)

Resources

There are various resources which are useful to contributors and team members.

• rustc Developer Guide
  • Documentation on compiler internals and setting up a developer environment.
• rustc Generated Documentation
  • rustdoc output for the compiler sources
• FIXMEH
  • An up-to-date list of all of the // FIXME comments in the compiler.

If there are additional resources which would be useful to a contributor or compiler team member, feel free to submit a PR to add it here.

Review Policy

This document describes our review policy for contributions to the Rust compiler. Its intended audience are contributors and reviewers as well.

The purpose of this policy is to help contributors shape pull requests that are easier to review - by clarifying the Rust project expectations - and for reviewers as well - by having a handy list of common things to check. The project will benefit if both parties have clear how to work together.

It is the purpose of code reviews to:

• Reduce the risk of introducing bugs and usability and performance regressions.
• Keep our code maintainable: readable, documented and well-tested.
• Ensure that changes are made with the big picture and appropriate context in mind. This is particularly relevant for changes that seem harmless in isolation but are problematic or undesirable in the larger context.

Reviewing accomplishes this by bringing in another set of eyes to look at a proposed change from a different perspective, which increases the chance of catching mistakes early and uncovering potential blind spots in the reasoning behind the change.

Basic Reviewing Requirements

There are a number of requirements that need to be met in order for reviewing to be effective:

• Reviewers must have a sufficient understanding of the code under review.
  • This is important to help spot non-obvious, unintentional side effects of a given change.
• Pull request authors must provide:
  1. A concise high-level description of the change and (2) the rationale behind it, unless the change is extremely trivial, like typo fixes.
  2. For the rationale to be even more useful, authors are encouraged to list potential points of contention, compromises that needed to be made, alternative approaches that have been considered, relevant documentation, discussions and context, etc.
  • Reviewing code is difficult, and reviewers only have a limited amount of time to do it. Jump-starting the review process by not making the reviewer puzzle together the intention and context of a pull request will not only speed things up but also improve the quality of the review.
• Reviewers must have a good idea on whether they are the right person to approve the change.
  • Knowledge of the code under review is an obvious but not the only criteria for answering this question.
  • Procedure wise, the reviewer also needs to decide:
    • Can the reviewer make the decision alone?
    • Does the PR need to go through an approval process?
    • Does the PR need reviews and/or sign-off from other teams, particularly t-lang?
    • Can the changes break stable code or begin accepting new code that we do not intend to? If the PR contains risks, is it sufficiently justified? Does the changes need ecosystem impact evaluation through crater runs?
    • Will the PR introduce significant perf changes? If there might be a perf regression, is it justified? Does the PR need a perf run?
    • Can the reviewer perform the review sufficiently thorough and in a timely fashion?
    • Is the reviewer impartial enough to provide a sufficiently unbiased perspective? e.g. due to co-authorship (sufficiently significant changes to the PR made by the reviewer) or other conflicts-of-interest?

Reviewing Checklist

The following list of questions will help reviewers and PR authors alike to bring PRs into good shape and meet the above criteria:

Checklist for PR authors and reviewers

• Does the PR message have..
  • ..a concise high-level description of the changes? (what is being changed)
  • ..a clear rationale for doing them? (why is it being changed)
  • ..if non-trivial and if suitable, how the bug is fixed or how the change is implemented?
  • ..a list of potential points of contention? alternatives? trade-offs? risks?
  • .links to relevant issues, RFCs, MCPs, etc?
• Does the PR need a regression test? Does the PR have sufficient test coverage?
• Does the change need to be covered by a major change proposal ([MCP])? Is it already covered? If there is already a MCP open, was it already accepted, or is the PR blocked on that?
• Does the PR need a perf run?
• Does the PR need reviews and/or sign-offs from other teams?
  • e.g. t-lang for lint expansions if the ecosystem impact is large or language changes
• Does the PR affect other teams in a non-trivial way? Should the affected teams get a heads-up?
  • e.g. changes to rustfmt or rust-analyzer or subtrees.
• Would someone trying to understand the PR in a year’s time be able to quickly reconstruct what’s going on?
• Is the new code properly documented? Is existing documentation still up-to-date?
• Does the changes in the PR need updates to the Reference or Edition Guide?
• Does the PR introduce a regression of any of the following:
  • Error message quality
  • Maintainability (e.g. complex code, no documentation, unsafe)
  • Any specific target platforms
  • Downstream tooling (e.g. linkers, debuggers)
  • Compile times
  • Memory usage
  • Targets (e.g. baselines, target features, calling conventions, etc.)

Checklist for reviewers

• Am I the right person to review this PR:
  • Does the changes in this PR fall under t-compiler purview?
  • Do I understand the code well enough?
  • Would I be able to spot non-obvious side effects?
  • Would I be able to fix a bug introduced by this PR?
  • Can I do the review in a timely fashion?
  • Do I feel pressure to quickly approve the PR for some reason?
  • Am I impartial enough?
• Before merging:
  • Is the PR title and description still accurate?
  • Is the commit history clean enough? We do not need 16 “fix typo” commits in the PR history.
  • Does the PR correctly/incorrectly close relevant issues?
• Do I need to roll reviewers from other relevant teams?

Guidance for dealing with common situations

In most cases common sense is enough for deciding how to apply this policy. However, sometimes there are gray areas where it is not immediately clear how to proceed. This section lists a few common cases together with guidance on how to deal with them.

I don’t think I am a good fit for reviewing - what now?

It is completely normal that you get (randomly) assigned a PR (via rustbot or otherwise) but don’t feel comfortable reviewing it. Here is what you can do, depending on the concrete case:

• If the change seems really big or contentious, consider recommending the author go through the appropriate approval process.
• If you know just the right person for the review, assign them via r? @<github-name>. It’s polite to leave a comment asking them if they can take over – but you don’t have to make sure beforehand that they can actually do it.
• If the change is not too complicated and you don’t expect that another randomly rolled compiler reviewer will also have trouble with the PR, you can reroll a random compiler reviewer with r? compiler.
• If the change is complicated, or you expect randomly rolling another compiler reviewer will just lead to multiple rerolls, you should open a thread in #t-compiler/private to ask the rest of the team – for someone who might be able to review it, or even if the team is comfortable with accepting the change at all.
• If the change is intended for another team, roll a reviewer from the relevant team (example: r? compiler).

You can also always ask for help on the #t-compiler Zulip stream for finding a reviewer. It is recommended, to the extent you are comfortable with, to do an initial review before passing the PR on to the final reviewer. This way the PR author will get helpful feedback sooner, subsequent reviewers will have less work to do, and you might also improve your own understanding of diverse areas in the compiler.

It is unclear if a contribution requires an approval decision

If you think a might contribution require broader team approval, check the Proposals, Approvals and Stabilization documentation. If a contribution doesn’t match any of the examples in that documentation, open a thread in #t-compiler/private and ask.

Discussion or rationale is too intransparent

Sometimes there are PRs that seem to be the result of some prior discussion, with no description or rationale. They usually have a title like “Change X” and the only content of the PR message is “r? @xyz”. Even though the change might make sense and may even have been suggested by a compiler team member, this is not good form.

Contributors may stumble across the PR several year later during bisections only to find the PR with absolutely zero context that was discussed offline or elsewhere, and the information is not available to future contributors. This is not good for maintainability. Including relevant context will very often help the PR author themselves in the future!

The PR message should give a self-contained description of what is being changed, why it is being changed and anything else that might be of interest.

Try to put yourself in the shoes of someone who, a few years down the road, needs to fix a bug related to the code touched by the PR and needs to reconstruct the rationale for the way things are.

Reviewer and PR author report to the same entity / work for the same employer

There is no rule that prevents two employees of the same company from reviewing each other’s PRs. We assume compiler team reviewers to act in good faith, and vest trust in team members to do so.

The concerns in such a case are no different than for any other two reviewers. We expect the mechanisms and principles we articulated above to be respected by all reviewers, whatever their employer. Does the PR concisely describe the changes that are being made? Does it give a clear, transparent rationale for why the changes make sense so that contributors down the line can follow the reasoning and reconstruct what’s going on? Have points of contention been discussed and cleared up? Then you are in the clear.

If you are in doubt if something is contentious, give a heads up to @rust-lang/compiler and ask for another opinion. If you think a might contribution require broader team approval, check the Proposals, Approvals and Stabilization documentation.

Reviewing and Mentoring

In the course of mentoring someone through a PR it often happens that the reviewer has ended up effectively co-writing the changes. This can be a tricky case because the reviewer is effectively approving their own changes. There are a number of considerations to take into account when deciding how to proceed:

• If the general direction of the changes has already been approved as part of an approval decision and the concrete advice given during mentoring was only concerned with resolving minor technical issues, then no further review is required.
• Similarly, if any contentious decisions have visibly been discussed and resolved on the PR with other compiler team members and the rest of the changes don’t deviate from the general direction that has been agreed upon then no further review is required either.
• If the PR was opened as a response to a concrete suggestion by the reviewer (and the changes are not entirely trivial) then it is advisable that the final review is done by someone else. However, the initial reviewer/mentor is encouraged to help bring the PR into good shape before handing it off.

In general, it is advisable to ask for a second opinion by someone knowledgable in the field in such cases, just to increase the chance of uncovering oversights and blindspots a mentor might have.

Nobody understands the code that’s being changed

Sometimes there is a bug in some code that nobody understands anymore. The original authors are unavailable and it is hard to gauge the implications of a proposed fix. In such a case it is a good idea for reviewers to I-compiler-nominated the PR (if they intend to stay the main reviewer) or assign a compiler team lead to the issue and add the S-waiting-on-team label.

In both cases, the PR will be brought in the weekly triage meeting. It is also especially valuable to gather and document as much information as possible about the issue, such as a description of the problem being fixed, points of unclarity, potential risks, alternatives that have been considered, et cetera. It is also a good idea to open a tracking issue to document the lack of understanding of such area, to document the specific questions, concerns and bugs, and it can be resolved if compiler team members regain better understanding.

Reviewers should ask PR authors to add this kind of information as comments in the code and/or to the PR message (which will become part of the git commit history).

PR makes a change to support use of rustc internals for external projects

This will need to be determined on a case-by-case basis.

In general, we should allow changes making things public, cleaning up things or making them more general, as long as the owners of the compiler region agree (so just assign to them).

As a concrete example: if someone is using the mir interpreter, and they want to make something public, it is likely not a problem, but there are some functions that are module- or crate-private on purpose, as they uphold invariants within the MIR interpreter. So basically, just assign such PRs to the relevant people (usually they get pinged anyway due to having told rustbot that they want to get pinged on changes to these parts).

Require a doc comment on such APIs identifying which external consumers the API concerns, and for what kinds of purpose.

If you think a might contribution require broader team approval, check the Proposals, Approvals and Stabilization documentation.

Note that this can non-obviously bound supposedly-internal compiler APIs to external consumers. Convey to the external consumers (that are not rust-lang/ projects) that we can offer the convenience so as long as it does not impose significant maintenance burden on the compiler, e.g. gets in the way of refactorings, and no hard stability guarantees are promised.

The PR is very large and complicated

Reviewers are not expected to stomach PRs that are very large and complicated. It is expected from contributors to split their work to make a review feasable, for example a series of more digestible PRs which are individually more logically self-contained. In general, before submitting large impact changes, it is expected the contributor to have discussed the design previously with the relevant team(s) so it is contributor’s duty to reference such discussions.

When in doubt, bring the PR to the attention of the team (through zulip threads and/or nominate for compiler triage meeting), and the team can decide if:

• The team can find suitable reviewers who can aid the PR author to break up the large change into smaller logical PRs that are possible to review on their own, but also in the context of the larger change.
• The team does not have the bandwidth, or team members are is not ready or willing or able to accept the large change as-is. In such cases, the team should make a decision to postpone or close, and clearly communicate the decision to the PR author to explain the reasoning. It is very frustrating if a PR stalls for many months only for it to be rejected anyway.

Technical Aspects of Reviewing

Every PR that lands in the compiler and its associated crates must be reviewed by at least one person who is knowledgeable with the code in question.

When a PR is opened, you can request a reviewer by including r? @username in the PR description. If you don’t do so, rustbot will automatically assign someone from the pool of reviewer candidates, determined by the files affected.

It is common to leave a r? @username comment at some later point to request review from someone else. This will also reassign the PR.

It is possible to request reviews from multiple reviewers, for example:

Rolling both a T-compiler and T-bootstrap reviewer as this PR contains both
compiler and bootstrap changes.

r? compiler
r? bootstrap

bors

We never merge PRs directly. Instead, we use bors. A qualified reviewer with bors privileges (e.g., a compiler team member) will leave a comment like @bors r+. This indicates that they approve the PR.

People with bors privileges may also leave a @bors r=username command. This indicates that the PR was already approved by @username. This is commonly done after rebasing.

Finally, in some cases, PRs can be “delegated” by writing @bors delegate+ or @bors delegate=username. This will allow the PR author or the delegated user to approve the PR by issuing @bors commands like the ones above (but this privilege is limited to the single PR).

Reverts

If a merged PR is found to have caused a meaningful unanticipated regression, the best policy is to revert it quickly and re-land it later once a fix and regression test are added.

A “meaningful regression” in this case is up to the judgment of the person approving the revert.

Some criteria to consider if a revert is warranted:

• A bug in a stable or otherwise important feature that causes code to stop compiling, changes runtime behavior, or triggers a (warn-by-default or higher) lint incorrectly in real-world code. Especially if the bug is reachable without any unstable feature gates.
• If a bug or change (incl. ICEs) is particularly easy to hit.
• If a bug or change significantly degrades contributor experience.
• If a test is flaky and unreliable.

When these criteria are in doubt, and especially if real-world code is affected, revert the PR. This has three benefits:

1. It allows bleeding edge users (esp. nightly or beta) to continue to use and report bugs on HEAD with a higher degree of certainty about where new bugs are introduced.
2. It takes pressure off the original PR author and the team, that no one is pressured to feel like they have to fix it immediately.
3. It might prevent the significant bug or regression from reaching another nightly/beta/stable build.

Before being reverted, a PR should be shown to cause a regression with a fairly high degree of certainty (e.g. bisection on commits, or bisection on nightlies with one or more compiler team members pointing to this PR, or it’s simply obvious to everyone involved). Only revert with lower certainty if the issue is particularly critical or urgent to fix.

Creating reverts

The easiest method for creating a revert is to use the “Revert” button on Github. This appears next to the “bors merged commit abcd” message on a pull request, and creates a new pull request.

Alternatively, a revert commit can be created using the git CLI and then uploaded as a pull request:

$ git revert -m 1 62d5bee

Don’t rely only on the default commit title and message created by git. Instead, title the revert commit meaningfully, and link to the relevant PR that introduced the regression. Link to the specific PR that is being fully or partially reverted. Link to relevant issues and discussions. Retain the commit hash being reverted.

Example revert commit title and message

Revert #131669 due to ICEs

Revert <https://github.com/rust-lang/rust/pull/131669> due to ICE
reports:

- <https://github.com/rust-lang/rust/issues/134059> (real-world)
- <https://github.com/rust-lang/rust/issues/134060> (fuzzing)

The changes can be re-landed with those cases addressed.

This reverts commit 703bb982303ecab02fec593899639b4c3faecddd, reversing
changes made to f415c07494b98e4559e4b13a9c5f867b0e6b2444.

It’s polite to tag the author and reviewer of the original PR so they know what’s going on. You can use the following message template for the revert PR description:

Reverts rust-lang/rust#123456
cc @author @reviewer

This revert is based on the following report of a regression caused by this PR:
<link to issue or comment(s)>

In accordance with the compiler team [revert policy], PRs that cause meaningful
regressions should be reverted and re-landed once the regression has been fixed
(and a regression test has been added, where appropriate).
[revert policy]: https://forge.rust-lang.org/compiler/reviews.html#reverts

Fear not! Regressions happen. Please rest assured that this does not
represent a negative judgment of your contribution or ability to contribute
positively to Rust in the future. We simply want to prioritize keeping existing
use cases working, and keep the compiler more stable for everyone.

r? compiler

Please include a temporary regression test in a separate commit to check that the regression is actually addressed by the revert commit. In a reland, this temporary regression test can be adapted or removed following improved test coverage as suitable.

If you have r+ privileges, you can self-approve a revert if the revert is clean and is unlikely to cause new regressions on its own, make sure the revert is not a case of “the cure is worse than the poison”. If non-trivial, please wait for a review – from the original reviewer or from another compiler reviewer via r? compiler. You can ask in #t-compiler if the matter is more urgent.

Generally speaking, reverts should have elevated priority and match the rollup status of the PR they are reverting. If a non-rollup PR is shown to have no impact on performance, it can be marked rollup=always. The revert author can coordinate with contributors authoring rollups to reschedule rollups or interleave the revert PR between rollups if suitable.

Forward fixes

Often it is tempting to address a regression by posting a follow-up PR that, rather than reverting the regressing PR, instead augments the original in small ways without reverting its changes overall. However, if real-world users have reported being affected, this practice is strongly discouraged unless one of the following is true:

• A high-confidence fix is already in the bors queue.
• The regression has made it to a release branch (beta or stable) and a backport is needed. Often the “smallest possible change” is desired for a backport (so that the fix doesn’t introduce new regressions). The offending PR may or may not still be reverted on the main branch; this is left to the discretion of someone who can r+ it.

While it can feel like a significant step backward to have your PR reverted, in most cases it is much easier to reland the PR once a fix can be confirmed. Allowing a revert to land takes pressure off of you and your reviewers to act quickly and gives you time to address the issue fully. It also is an opportunity to take a step back and reassess the test coverage.

Rollups

All reviewers are strongly encouraged to explicitly mark a PR as to whether or not it should be part of a rollup. This is usually done either when approving a PR with @bors r+ $ROLLUP_STATUS or with @bors $ROLLUP_STATUS where $ROLLUP_STATUS is substituted with one of the following:

• rollup=always: These PRs are very unlikely to break tests or have performance implications. Example scenarios:
  • Changes are limited to documentation, comments, etc. that is highly unlikely to fail a build.
  • Changes cannot have performance implications.
  • Your PR is not landing possibly-breaking or behavior altering changes.
    • Feature stabilization without other changes is likely fine to rollup, though.
  • When in doubt do not use this option!
• rollup=maybe: This is the default if @bors r+ does not specify any rollup status at all. Use this if you have some doubt that the change won’t break tests. This can be used if you aren’t sure if it should be one of the other categories. Since this is the default, there is usually no need to explicitly specify this, unless you are un-marking the rollup level from a previous command.
• rollup=iffy: Use this for mildly risky PRs (more risky than “maybe”). Example scenarios:
  • The PR is large and non-additive (note: adding 2000 lines of completely new tests is fine to rollup).
  • Has platform-specific changes that are not checked by the normal PR checks.
  • May be affected by MIR migrate mode.
• rollup=never: This should never be included in a rollup (please include a comment explaining why you have chosen this). Example scenarios:
  • May have performance implications.
  • May cause unclear regressions (we would likely want to bisect to this PR specifically, as it would be hard to identify as the cause from a rollup).
  • Has a high chance of failure.
  • Is otherwise dangerous to rollup.
    • Messes too much with:
    • LLVM or code generation
    • bootstrap or the build system
    • build-manifest
• rollup: this is equivalent to rollup=always
• rollup-: this is equivalent to rollup=maybe

Priority

Reviewers are encouraged to set one of the rollup statuses listed above instead of setting priority. Bors automatically sorts based on the rollup status (never is the highest priority, always is the lowest), and also by PR age. If you do change the priority, please use your best judgment to balance fairness and urgency with other PRs.

The following is some guidance for setting priorities:

• 1-5
  • P-high issue fixes
  • Toolstate fixes
  • Reverts containing the above
  • Beta-nominated PRs
  • Submodule/Subtree updates
• 5+
  • P-critical issue fixes
• 10+
  • Bitrot-prone PRs (particularly very large ones that touch many files)
  • Urgent PRs (e.g. urgent reverts)
  • Beta backports
• 20+
  • High priority that needs to jump ahead of any rollups
  • Fixes or changes something that has a high risk of being re-broken by another PR in the queue.
• 1000
  • Absolutely critical fixes
  • Release promotions

Expectations for r+

bors privileges are binary: the bot doesn’t know which code you are familiar with and what code you are not. They must therefore be used with discretion. Do not r+ code that you do not know well – you can definitely review such code, but try to hand off reviewing to someone else for the final r+.

Similarly, never issue a r=username command unless that person has done the review, and the code has not changed substantially since the review was done, and that the person has explicitly indicated that another contributor can r= on their behalf.

Rebasing is fine and often necessary, but changes in functionality typically require re-review. It is very helpful for the reviewer if the PR author can produce a brief summary of what has changed since last review, in addition to responding to individual review comments.

Please refer to bors documentation for bot usage.

Social aspects of reviewing

First and foremost, PR authors and compiler reviews alike are expected to uphold the Code of Conduct. Simply speaking, a reviewer is expected to be respectful to the PR author, even if the reviewer disagrees with the changes.

Reviewers are encouraged to consider matters from the perspectives of the PR author too. If a change is stuck due to procedural reasons or reviewer bandwidth for months without any resolution (including a resolution that the compiler might not be ready to accept such a change at present time, but thank the PR author for the contributions anyway), and accrues constant merge conflicts, it can be very frustrating.

If some discussions are getting heated, ask the moderation team to step in.

Proposals, Approvals and Stabilization

It is very common to need to gather feedback and approval when contributing to the compiler, either for permission to proceed with an experiment or refactoring, or when stabilizing a feature. This document aims to summarise the various processes that the compiler team has for making approval decisions and when each should be used.

Approvals

There are three mechanisms that the team can use to approve a proposal (not all approval mechanisms are suitable for each method of making a proposal - see below):

• r+
  • A proposal is r+’d when it is approved to be merged.
  • r+ can only be used to approve a PR.
• Seconding
  • A proposal is second’ed when a team member formally endorses the proposal. It is intended that seconding only occur once discussion has concluded and team members have had time to raise concerns. Seconding tentatively accepts a proposal subject to a ten-day waiting period for other team members to raise any concerns.
  • Seconding can only be used to approve a MCP.
• FCP
  • A final comment period will require sign-off from a majority of the compiler team to approve a proposal and then a ten day waiting period.
  • FCPs can be used to approve any form of proposal.

Proposals

There are three ways to propose a change to the compiler team. The appropriate choice depends on the nature of the proposal, described below.

• Request For Comments (RFC)
  • RFCs are pull requests to the rust-lang/rfcs repository and are a heavy-weight proposal mechanism, reserved for significant changes.
  • RFC proposals can only be approved by FCPs.
• Major Change Proposal (MCP)
  • MCPs are issues in the rust-lang/compiler-team repository and are a medium-weight proposal mechanism, suitable for most proposals. MCPs are recommended for written proposals that are not end-user facing.
  • Introduced in RFC 2904.
  • MCP proposals can be approved by FCPs or Seconding.
• Pull Request (PR)
  • PRs are pull requests to the rust-lang/rust repository and are a light-weight proposal mechanism, suitable for most proposals. PRs are preferred when the proposal is accompanied by a small patchset (such as stabilization of a compiler flag or addition of a new target).
  • PR proposals can be approved by FCPs or r+.

How do I submit an MCP?

• Open a tracking issue on the rust-lang/compiler-team repo using the [major change template].
  • A Zulip topic in the stream #t-compiler/major changes will automatically be created for you by a bot.
  • If concerns are raised, you may want to modify the proposal to address those concerns.
  • Alternatively, you can submit a design meeting proposal to have a longer, focused discussion.
• To be accepted, a major change proposal needs three things:
  • A second, a member of the compiler team who approves of the idea, but is not the one originating the proposal.
  • A final comment period (a 10 day wait to give people time to comment).
    • The FCP can be skipped if the change is easily reversed and/or further objections are considered unlikely. This often happens if there has been a lot of prior discussion, for example.
• Once the FCP completes, if there are no outstanding concerns, contributions can begin.
  • An earlier accepted MCP is not a substitute for any later necessary approvals.

What kinds of comments should go on a MCP in the compiler-team repo?

Please direct technical conversation to the Zulip stream.

The compiler-team repo issues are intended to be low traffic and used for procedural purposes.

It is recommended that any team member who wishes to “second” a proposal be familiar with the relevant code. Anyone can note concerns that shouldn’t be overlooked.

How does one second an MCP or raise an objection?

These types of procedural comments can be left on the issue (it’s also good to leave a message in Zulip). See the previous section. To facilitate a machine parsable scanning of the concerns please use the following syntax to formally register a concern:

@rfcbot concern reason-for-concern

<long description of the concern>

And the following syntax to lift a concern when resolved:

@rfcbot resolve reason-for-concern

MCPs can be seconded using:

@rfcbot second

Who decides whether a concern is unresolved?

Usually the experts in the given area will reach a consensus here, but if there is some need for a “tie breaker” vote or judgment call, the compiler team leads make the final call.

When should MCPs be closed?

MCPs can be closed:

• by the author, if they have lost interest in pursuing it.
• by a team lead or expert, if there are strong objections from key members of the team that don’t look likely to be overcome.
• by folks doing triage, if there have been three months of inactivity. In this case, people should feel free to re-open the issue if they would like to “rejuvenate” it.

What happens if someone makes a contribution that requires an approval and doesn’t have one?

If the approval required for the contribution requires an MCP or an RFC, then the contribution should be closed or marked as blocked, with a request to create an MCP or RFC first. If approval of a PR is acceptable for the specific contribution (see below), then the approval process can begin.

Can I work on code experimentally before a approval is gained?

Of course! You are free to work on PRs or write code. But those PRs should be marked as experimental and they should not land, nor should anyone be expected to review them (unless folks want to).

What makes a good proposal?

A good proposal will address the following:

• Motivation: Why is this proposal necessary? What problem does it solve? Why is that problem important?
• Design: What are you proposing?
• Implementation notes: You don’t have to talk about the implementation normally, but if there are any key things to note (i.e., it was very invasive to implement), you might note them here.
• Precedent, links, and related material: Have there been similar proposals on other compilers/linkers/tools, like clang or lld?
• Alternatives, concerns, and key decisions: Were there any alernatives considered? If so, why did you pick this design?

What proposal/approval do I need?

This section aims to exhaustively detail which proposal and approval is necessary for any given circumstance.

Internal

• Creating a notification group
  • Propose using: PR
  • Approve using: r+
  • If a team member finds the new group reasonable then they can merge the change adding the group.
• Significant internal refactorings/changes
  • Propose using: MCP
  • Approve using: Seconding
  • Describe your proposed refactorings in detail in an MCP - optionally scheduling a steering meeting if more focused discussion is necessary. Once discussion has concluded, a team member may second the proposal
• Defining/changing small team policies
  • Propose using: MCP
  • Approve using: Seconding
  • Examples of smaller policy changes where an MCP would be sufficient include our level of support for case-insensitive filesystems or whether the team intend tracking issues to host discussion
• Defining/changing large team policies
  • Propose using: RFC
  • Approve using: FCP
  • Larger policy changes requiring an FCP include proposals to the team’s structure and membership criteria, etc

Compiler flags

• Adding a compiler option for internal-use only (e.g. -Ztreat-bug-as-err)
  • Propose using: PR
  • Approve using: r+
  • If a team member finds the new option reasonable then they can merge the change adding the option
• Adding a simple compiler option with intent to later stabilize
  • Propose using: MCP
  • Approve using: Seconding
  • Simple options, such as exposing an uncontroversial option from LLVM, can be implemented and merged with a seconded MCP and r+ approval from a reviewer. It will need a full FCP when it is later stabilized
• Adding a complex compiler option with intent to later stabilize
  • Propose using: RFC
  • Approve using: FCP
  • If the option is complicated and requires design considerations, then write and submit a t-compiler RFC
• Removing internal-use only flags
  • Propose using: MCP
  • Approve using: Seconding
  • Describe the rationale for removing the unstable implementation. Once discussion has concluded, a team member may second the proposal
• Removing flags which were intended for eventual stabilization
  • Propose using: MCP
  • Approve using: Seconding
  • Describe the rationale for removing the unstable implementation. Once discussion has concluded, a team member may second the proposal
• Stabilizing a compiler option
  • Propose using: PR
  • Approve using: FCP
  • Open a PR and follow the stabilization guide. The assigned reviewer will check that the stabilization guide has been followed, review the code and start an FCP
• Reverting stabilization of a compiler option
  • Propose using: PR
  • Approve using: FCP
  • Open a PR and follow the stabilization guide. The assigned reviewer will check that the stabilization guide has been followed, review the code and start an FCP
• Extending the behavior of a stable flag
  • Propose using: MCP
  • Approve using: Seconding
  • Describe the rationale for extending the behavior of the flag. Once discussion has concluded, a team member may second the proposal

Attributes

• Adding a attribute for internal-use only (e.g. rustc_attrs)
  • Propose using: PR
  • Approve using: r+
  • If a team member finds the new attribute reasonable then they can merge the change adding the attribute
• Adding a attribute with intent to later stabilize
  • Follow the language team’s process and have the implementation PR reviewed by a member of the compiler team
• Removing internal-use only attributes
  • Propose using: MCP
  • Approve using: Seconding
  • Describe the rationale for removing the unstable implementation. Once discussion has concluded, a team member may second the proposal
• Removing attribute which were intended for eventual stabilization
  • Follow the language team’s process and have the removal PR reviewed by a member of the compiler team
• Stabilizing an attribute
  • Follow the language team’s process and have the stabiization PR reviewed by a member of the compiler team
• Reverting stabilization of an attribute
  • Follow the language team’s process and have the revert PR reviewed by a member of the compiler team

Features

• Adding experimental implementations of not-yet-proposed language features
  • Propose using: MCP
  • Approve using: Seconding
  • With the approval of the language team (that they think the feature is worth experimentation), then submit an RFC and if, after discussion has concluded, a compiler team member agrees that the implementation is feasible and will not put undue burden on the maintainers of the compiler, then they can second the MCP and implementation can proceed.
  • This isn’t necessary if the owner of the implementation is a member of the compiler team
• Stabilizing a language feature
  • Follow the language team’s process and have the stabiization PR reviewed by a member of the compiler team
• Reverting stabilization of a language feature
  • Follow the language team’s process and have the revert PR reviewed by a member of the compiler team

Targets

• Proposing a new target
  • Propose using: PR
  • Approve using: r+ (compiler leads)
  • You can r? compiler_leads on the PR to roll one of the compiler leads as the reviewer.
  • Open a PR with the new target (w/ relevant documentation updates) and document adherence to the target tier policy in the description. New targets must start as tier three
  • New targets should be assigned to the compiler team co-leads to check for any licensing concerns
• Promoting a target
  • Propose using: PR
  • Approve using: r+ (compiler leads)
  • Open a PR with the new target and document adherence to the target tier policy in the description
  • New targets should be assigned to the compiler team co-leads to ensure that any demands on the project infrastructure are considered and checked with relevant teams
• Demoting/removing a target
  • Propose using: MCP
  • Approve using: FCP
  • Write an MCP describing why the target should be demoted/removed and once discussion has concluded, an FCP can be started to approve the demotion/removal.
• Changing target baseline (e.g. minimum Darwin or Windows version bump)
  • Propose using: MCP
  • Approve using: FCP
  • Write an MCP describing why the target should have a change of baseline and once discussion has concluded, an FCP can be started to approve the change of baseline.
• Adding/removing target maintainers
  • Propose using: PR
  • Approve using: r+
  • Open a PR with the changes to the target documentation and obtain an r+ from the reviewer.
• Adding a target feature
  • Propose using: PR
  • Approve using: r+
  • Open a PR adding the target feature and obtain an r+ from the reviewer.
• Stabilizing a target feature
  • Propose using: PR
  • Approve using: FCP
  • Open a PR stabilizing the target feature and once the reviewer is happy with the changes, an FCP can be started

Lints, errors and warnings

• Adding a new warning/error
  • Propose using: PR
  • Approve using: r+
  • Open a PR with the implementation and obtain an r+ from the reviewer
• Adding a new lint group
  • Follow the language team’s process and have the implementation PR reviewed by a member of the compiler team
• Adding a new lint related to compiler features
  • Propose using: MCP
  • Approve using: FCP
  • A lint concerning a detail that is otherwise the responsibility of the compiler team (such as compiler flags) is the responsibility of the compiler to approve, rather than the language team.
  • Write an MCP describing the lint and its justification and once discussion has concluded, an FCP can be started to approve the new lint
• Adding a new future compatibility warning (FCW) related to compiler features
  • Propose using: MCP
  • Approve using: FCP
  • A FCW concerning a detail that is otherwise the responsibility of the compiler team (such as compiler flags) is the responsibility of the compiler to approve, rather than the language team.
  • Write an MCP describing the FCW and its justification and once discussion has concluded, an FCP can be started to approve the new FCW
• Changing default lint level of a lint related to compiler features
  • Propose using: MCP
  • Approve using: FCP
  • A lint concerning a detail that is otherwise the responsibility of the compiler team (such as compiler flags) is the responsibility of the compiler to approve, rather than the language team.
  • Write an MCP describing the rationale for changing the default lint level and once discussion has concluded, an FCP can be started to approve the new lint
• Adding a new lint related to language features
  • Follow the language team’s process and have the implementation PR reviewed by a member of the compiler team
• Adding a new future compatibility warning (FCW) related to language features
  • Follow the language team’s process and have the implementation PR reviewed by a member of the compiler team
• Changing default lint level of a lint related to language features
  • Follow the language team’s process and have the implementation PR reviewed by a member of the compiler team

Licensing

• Introducing a new dependency/license change/dependency bump
  • Propose using: PR
  • Approve using: r+ (compiler leads)
  • Open a PR with the change affecting licensing and assign it to the team leads for review

Adding ecosystem/integration test jobs/components to rust-lang/rust CI

See Adding ecosystem/integration test jobs/components to rust-lang/rust CI.

Adding ecosystem/integration test jobs/components to rust-lang/rust CI

Scope

This policy is applicable to proposals for adding new ecosystem and integration test jobs/components that involve building and testing additional artifacts which may cause rust-lang/rust PR CI or Full CI (the “CI”) to fail, or produce a failure message, that may impact other rust-lang/rust contributors who also use the rust-lang/rust CI.

For example (non-exhaustive):

• Ecosystem test jobs: Rust for Linux or Fuchsia.
• Integration test components: GCC codegen backend or Cranelift codegen backend.

Background

rust-lang/rust runs a small set of build/test jobs on PR CI (faster, less expensive/exhaustive), and runs a much larger set of build/test jobs on Full CI. PR CI usually takes around an hour, while Full CI usually takes around 3 hours. Having ecosystem and integration test jobs/components that:

• may spuriously fail; or
• may genuinely fail but it’s not clear who should be consulted about the failure or who is responsible for fixing the failure; or
• otherwise do not have well documented test job maintainers and failure protocol;

can introduce a lot of friction and frustration for other contributors who now will have to deal with the failure or understand why the test job failed in the first place, which may now be blocking their PR. Everyone utilizing the rust-lang/rust CI is expected to use it responsibly.

To help with this, please follow the process described below if you would like to propose adding an ecosystem/integration test job/component to the rust-lang/rust CI.

Process for adding an ecosystem/integration test job/component to rust-lang/rust CI

1. Ask the Infrastructure Team on zulip (#t-infra) to check if there would be capacity for the proposed test job/component.
2. Propose using a Major Change Proposal (MCP).
   • Including the filled out Ecosystem and Integration Test Job/Component Policy (see below).
3. Once the MCP is seconded and accepted, create a new issue on rust-lang/rust about the proposal, linking to the MCP, and then nominate the proposal for library team review via @rustbot label +I-libs-nominated.
   • Link to the MCP.
4. Once the library team reviews the proposal and has no blocking concerns, submit the implementation PR to rust-lang/rust.
   • The PR should include an accompanying Ecosystem/Integration Test Job/Component support page in the in-tree rustc-dev-guide, ensuring that the Failure Protocol is well-documented (see below). Link to the MCP and issue.
5. The Infrastructure Team will review the implementation PR. Once approved, the ecosystem/integration test job/component will run in rust-lang/rust PR CI or Full Merge CI.

Ecosystem and Integration Test Job/Component Policy

Please copy and fill out this template (below the separator) as part of the MCP. The policy questions/explanation themselves will be quoted blocks. Information that the MCP author is expected to provide are indicated by italicized sentences whose content should be replaced.

NOTE: It is not the intention of this policy to make it frustrating annoying to add an ecosystem test job/component. We simply wish to gather the necessary background information upfront (especially working together to figure out a viable Failure Protocol) to minimize potential frustrations from other rust-lang/rust contributors if and when the the test job/component do fail, potentially blocking PR / Full Merge CI in completely unrelated PRs.

## Ecosystem and Integration Test Job/Component Policy

The ecosystem/integration test job/component ("test job/component") proposed for the
[rust-lang/rust] CI must:

- Be approved by the compiler team through a proposed MCP, where the MCP is seconded by a compiler
  team member, and the MCP is accepted with no blocking concerns.
- Have no blocking concerns from the library team.
- Have the implementation PR be reviewed and approved by the infrastructure team.
- Be properly documented on [rustc-dev-guide] (preferably as part of the implementation PR).

Please complete the sections below so [rust-lang/rust] teams can have sufficient context about the 
proposed test job/component.

### Test job/component rationale

> What does this test job/component do?
>
> - If an ecosystem test job/component is being proposed, can you briefly describe the intended
>     ecosystem users?

*Please provide responses here, replacing this sentence.*

> What [rust-lang/rust] changes can potentially break the test job/component?
>
> E.g. changes to rustc, standard library, bootstrap or tools (like clippy/rustfmt/cargo).

*Please provide responses here, replacing this sentence.*

> Why does this test job/component need to be part of the [rust-lang/rust] PR and/or Full Merge CI?

*Please provide responses here, replacing this sentence.*

> If the test job/component will block on failure, why does it need to block?

*Please provide responses here, replacing this sentence.*

> If the test job/component will not block on failure initially but is intended to eventually become
> blocking:
>
> - Why will it become blocking?
> - When will it become blocking?

*Please provide responses here, replacing this sentence.*

### Test job/component maintainers

> The proposed test job/component for [rust-lang/rust] CI must have at least one dedicated test
> job/component maintainer. The test job/component maintainers understand that they will be pinged
> or otherwise contacted about the ecosystem/integration test job/component, particularly for (but 
> not limited to) its failures.
>
> **Please list who will be maintaining this ecosystem/integration test job/component here. Please
> format the github handles in the style:**
>
> ```
> [@github_handle_1](https://github.com/github_handle_1)
> [@github_handle_2](https://github.com/github_handle_2)
> ```
>
> NOTE: For future readers, you can paste the usernames without formatting them as links via
> **ctrl-shift-v**.

*Please list test job/component maintainers here with the formatting advice above, replacing this
sentence.*

> **NOTE: If an ecosystem/integration test job/component no longer has an active dedicated
> maintainer (or maintainers), and if [rust-lang/rust] teams find the ecosystem/integration test
> job/component causes significant burden or becomes irrelevant, then the ecosystem/integration test
> job/component may be removed.**

### CI infrastructure considerations

> You should ask the Infrastructure Team on the
> [`#t-infra`](https://rust-lang.zulipchat.com/#narrow/channel/242791-t-infra) zulip channel when
> proposing a new ecosystem/integration test job/component to check if there's capacity for the test
> job/component.
>
> - Does the ecosystem/integration test job/component require substantial CI resources (storage and/
>   or CI time)? In particular, will it require large runners?

*Please provide responses here, replacing this sentence. If there is a zulip topic discussing it
with the Infrastructure Team, please include the zulip topic link here.*

### Features and implementation details

> Does the proposed test job/component intend to use any unstable features?
>
> - If so, are the unstable features ready for exposure (e.g. must an unstable feature be completely
>   reworked)?
> - For ecosystem test jobs/components, are the unstable features ready for such exposure to the
>   ecosystem, and are the feature stakeholders ready for such usage?

*Please provide responses here, replacing this sentence.*

> Does the proposed test job/component intend to intentionally depend on any implementation details?
> This may include but is not limited to: unstable/internal compiler/tool flags and behaviors,
> `RUSTC_BOOTSTRAP` usages, standard library implementation details, etc.
>
> - If so, are there plans to shrink or expand such dependencies in the future?

*Please provide responses here, replacing this sentence.*

### Failure protocol: what to do if the job/component breaks/fails?

> **NOTE: If the artifacts of an ecosystem/integration test job/component are not shipped as part of
> a distribution component/toolchain, the test job/component may be temporarily disabled to unblock
> [rust-lang/rust] PR CI or Full Merge CI without receiving prior approval from the test
> job/component maintainers. The test job/component maintainers will be pinged or otherwise notified
> about the test job/component being disabled.**

> How can the test job/component maintainers be contacted in case of failure? By default, it is
> assumed that the test job/component maintainer can be pinged via their GitHub handles.

*Please provide responses here, replacing this sentence.*

> (If applicable) If the addition of an ecosystem/integration test job is being proposed:
>
> - How can the test job be run in CI? If so, is there a try job (`try-job: ...`) invocation? What's
>   the job name?
> - Can the test job be run locally? If so, how?

*If applicable, please provide responses here, replacing this sentence. Otherwise, you can ignore
this question.*

> (If applicable) If the addition of an ecosystem/integration test component is being proposed:
>
> - Which existing CI jobs will be building and testing this test component?
> - Can they be built and ran as part of a try job? If so, what are the job names and the try job
>   (`try-job: ...`) invocations?
> - Can the test component be built and run locally? If so, how?

*If applicable, please provide responses here, replacing this sentence. Otherwise, you can ignore
this question.*

> How can the test job/component be disabled in the event of spurious failures that are blocking PR
> and/or Full Merge CI?

*Please provide responses here, replacing this sentence.*

> If a PR breaks the test job/component:
>
> - If the breakage seems **spurious** and retrying does not resolve the spurious breakage, the test
>   job may be **temporarily disabled** (see below).
> - If the breakage is **intentional**, how will this be resolved?
> - If the breakage is **unintentional**, is the PR author expected to fix the breakage?

*Please provide responses here, replacing this sentence.*

### Dependencies, build/test environments and reliability

> Does the test job/component involve any custom build systems that are not used in the regular
> [rust-lang/rust] CI jobs?

*Please provide responses here, replacing this sentence.*

> Does the test job/component depend on external resources (e.g. external servers) that may be
> subject to network connectivity?
>
> - If so, does the infrastructure team need to help maintain a mirror of the required assets?

*Please provide responses here, replacing this sentence.*

> Are there any potential sources of spurious failures due to the test job/component?

*Please provide responses here, replacing this sentence.*

> Are there any other unusual requirements (build environment, dependencies, etc.)?

*Please provide responses here, replacing this sentence.*


[rust-lang/rust]: https://github.com/rust-lang/rust
[rustc-dev-guide]: https://github.com/rust-lang/rustc-dev-guide

Third-party and Out-of-tree Crates Policy

This policy describes the guidelines for creating out-of-tree crates for use in the compiler and using third-party crates within the compiler.

Out-of-tree crates

One of the primary goals of this policy is to ensure that there is consistency in how out-of-tree crates used in the compiler are set up (at least, those maintained by the compiler team and living in rust-lang) and that the experience is uniform across rust-lang/rust and these crates.

When should parts of the compiler be extracted into an out-of-tree crate?

This is left to the discretion of compiler team members but should be discussed with the rest of the team, either through raising the question at the weekly triage meeting or asynchronously using an approval decision. If the crate is a product of a working group, there should already be agreement within the working group that an out-of-tree crate is suitable.

When considering creating an out-of-tree crate, it is worth balancing how general the crate should be with the increased maintenance burden that this may bring if widely used.

Where should compiler crates live?

Out-of-tree compiler crates should be hosted in the rust-lang organization - this simplifies integration with external infrastructure tooling and will inherit existing team permissions on GitHub. It should be made clear in any documentation that the compiler team and any appropriate working groups are responsible for the crate. It is not recommended to start with a prototype in another organization or personal repository.

Can existing out-of-tree crates from personal accounts or other organizations be transferred?

Yes, this is encouraged. In order to do this, discuss this with the team and familiarize yourself with the GitHub documentation for repository transfers and then arrange to perform the transfer. Once a transfer is complete, a redirect will exist in the original account or organization and this will conflict with the names of any new forks of the transferred repository - an email to GitHub is required to resolve this.

Who owns these crates?

It is desired that a compiler team member or working group has loose ownership over a crate so that there are clear owners who are responsible for making sure that new versions are published and that pull requests are reviewed.

Sometimes a non-project member is the primary owner of a crate and the compiler team are added as “fallback” maintainers in case the primary maintainer is no longer reachable. This is discouraged but can be justified on a case-by-case basis.

What should these crates be named?

Crate naming will be discussed when new out-of-tree crates are proposed to the compiler team.

Crate naming will differ on a case-by-case basis. Crates that are inherently tied to the compiler would benefit from a name that is prefixed with rustc_. This is an indicator of how stable the crate may be to prospective users. Other crates, which are more general-purpose, will have names that are disentangled from the compiler.

Are there any limitations on the review policy for out-of-tree crates?

Generally, the working groups and team members that are primarily free to maintain the crate using whatever practices are best suited to their group, however, there are some limitations so that there is some uniformity across the compiler and out-of-tree crates:

• Everyone with r+ on rust-lang/rust should be able to review and approve PRs.
• Where possible, only active participants in the crate (or related working group) need be on the review rotation for the crate.
• It is fine to have additional reviewers on the crate who do not otherwise have r+ for Rust as a whole, if those reviewers are actively involved in the working group or crate maintenance.
• Major pull requests should have multiple reviewers.

What is required of an out-of-tree crate?

It is required that out-of-tree crates must:

• Be dual-licensed with Apache 2.0 and MIT when maintained by the compiler team (as the compiler is) unless there is a compelling reason to do otherwise.
  • If another license is desired, this must be brought up when proposing the new crate for compiler team members to agree. Prefer licenses accepted by tidy, unless otherwise required (ports of code from other projects, etc).
• Abide by Rust’s code of conduct.
• Specify that the crate is maintained by the Rust compiler team and any appropriate working groups.
  • In particular, this should detail the expected level of maintenance and stability for any prospective users.
  • This should also link to the working group details in this repository.
• Be added to the list at the bottom of this page.
• Follow semantic versioning.
• Use GitHub merge queues and @triagebot.
• Use labels that are compatible with the existing triage process. This will allow nominated issues in your out-of-tree crate to be discussed during triage meetings.
  • eg. T-compiler, I-compiler-nominated (a full list is to be decided)

Is there a requirement for community infrastructure for an out-of-tree crate?

There is no requirement that community infrastructure (such as Zulip servers/streams) be created for out-of-tree crates. This may be desirable if an out-of-tree crate gains a large community of contributors and users, but otherwise, the working group or compiler team streams should be used initially.

Linkifiers for auto-linking to issues and PRs on the primary Rust Zulip server can be added on request.

Are there any recommendations for working with out-of-tree crates?

Recommendations for working with out-of-tree crates will be documented in the rustc-dev-guide (see rust-lang/rustc-dev-guide#285 for progress).

How should stabilization/semantic changes be handled in out-of-tree crates?

It is important to involve the language team in any changes in out-of-tree crates that would result in stabilization or semantic changes to the language. Submodule changes in PRs to rust-lang/rust should be labelled appropriately (eg. relnotes, t-compiler, t-lang) just as if the change were implemented in rust-lang/rust directly, include a description of the changes when it is not obvious to those unfamiliar with the compiler or the out-of-tree crate.

In summary, the process for establishing an out-of-tree crate is as follows:

1. Where appropriate, discuss and confirm the need within the working group for the out-of-tree crate.
2. Create a PR modifying this document to include the crate in the list below. Use @rfcbot merge to gain agreement from compiler team members.
3. Create a new repository in the rust-lang organization using the teams repository.

   1. Ensure that the access.teams.compiler key is set to 'maintain' so that the team have appropriate permissions.

   2. Add a README describing the intended purpose of the crate, which team and working group are responsible (link to their page in this repository) and the intended level of maintenance and stability.

      This crate is developed and maintained by the Rust compiler team for use within rustc, in particular, it is the responsibility of the .template working group. This crate [will have regular breaking changes and provides no stability guarantees|is intended to remain stable and have limited breaking changes].

   3. Include the LICENSE-APACHE and LICENSE-MIT files from rust-lang/rust.

   4. Include or link the CODE_OF_CONDUCT file from rust-lang/rust.

   5. Create a relevant .gitignore (here’s a sane default).

   6. Create P-high, P-medium, P-low, I-compiler-nominated and T-compiler labels.

4. Perform any initial development required before integration with rustc.
5. Publish initial version, following semantic versioning.
6. Add the crate as a dependency to the appropriate in-tree crate and start using.

Third-party crates

It is sometimes desirable to use the functionality of an existing third-party crate in the compiler.

When can a third-party crate be added as a compiler dependency?

It is desirable that a third-party crate being included in the compiler is well-maintained and that, where possible, a compiler team member is added as a maintainer. You should consult with the rest of the compiler team before making this decision.

What about third-party dependencies to out-of-tree crates?

The same policies apply to all compiler-team-maintained crates used in the compiler.

List of out-of-tree crates

This section contains the list of existing out-of-tree, compiler team-maintained crates:

• rust-lang/chalk
• rust-lang/polonius
• rust-lang/measureme
• rust-lang/thorin

Prioritization

It is important that the compiler team can quickly identify priority issues, hence the establishment of a prioritization process, described below.

General Process

1. Ascertain the current status of the issue
2. Try progressing the issue if possible (e.g. request updates from the issue author/reviewer)
3. Is there an MCVE for the issue already?
4. Check if it’s a regression and label it accordingly (regression-* labels)
5. Figure out the area the issue belongs and label it accordingly (A-* labels)
6. Ping notify groups or relevant teams
7. Assign if possible

Priority Levels

As the compiler team’s resources are limited, the primary goal of prioritization is to identify the most relevant issues to work on, so that the compiler team can focus on what matters the most.

Issues relevant to prioritization are bugs and feature requests that are nominated for prioritization, by adding the I-prioritize label as described below.

Labels

Labeling an issue as I-prioritize starts the prioritization process, which will end by removing the I-prioritize label and appending one of the 4 labels we will discuss below:

• P-critical
• P-high
• P-medium
• P-low

Each of these labels defines a strategy the team will adopt regarding:

• The amount of focus a given issue will receive
• How members of the community can get involved

P-critical

A P-critical is an issue potentially blocking a compiler release (i.e. highly recommended to be solved before a new compiler release). These issues will be raised at the compiler team’s triage meeting on a weekly basis.

Examples of things we typically judge to be “critical” bugs:

• Regressions where code that used to compile no longer does
  • Mitigating conditions that may lower priority:
    • If the code should never have compiled in the first place (but if the regression affects a large number of crates, this may indicate that we need a warning period)
    • If the code in question is theoretical and considered unlikely to exist in the wild, or if it only exists in small, unmaintained packages that are not widely used
  • If a regression has been in stable for a release or two (either because we are still awaiting a fix, or because the bug had laid dormant i.e. undetected), we typically lower the priority as well, because by that time, if the users have not raised a ruckus about the regression, that is a sign that it is inherently not a critical issue.
    • e.g. an issue that would have been P-critical but ended up being P-high
• Regressions where code still compiles but does something different than it used to do (dynamic semantics have changed)
  • Mitigating conditions that may lower priority:
    • If code uses feature that is explicitly not specified (e.g. std::vec::Vec docs state order in which it drops its elements is subject to change)
• Feature-gated features accessible without a feature gate
  • Mitigating conditions that may lower priority:
    • If the pattern is very unlikely
• Soundness holes with real-world implications
  • Mitigating conditions that may lower priority:
    • Soundness holes that are difficult to trigger
    • Soundness holes that will not affect stable, e.g. if the hole makes use of a gated unstable feature.
• Diagnostic regressions where the diagnostic is very common and the situation very confusing
• ICEs for common scenarios or code patterns
  • Mitigating conditions that may lower priority:
    • If the code that triggers the ICE also triggers compilation errors, and those errors are emitted before the ICE
    • If the code in question makes use of unstable features, particularly if the ICE requires a feature gate

A P-critical issue will receive the most attention. It must be assigned one or several people as soon as possible, and the rest of the team should do their best to help them out if/when applicable.

P-high

P-high issues are issues that need attention from the compiler team, but not to the point that they need to be discussed at every meeting. They can be P-critical issues that have a mitigating condition as defined above, or important issues that aren’t deemed blockers.

Because there are too many P-high issues to fit in every compiler meeting, they should rather be handled asynchronously by the team’s prioritization, in order to help them move forward. They can still occasionally be brought up at meetings when it is deemed necessary.

The effectiveness of the team’s prioritization will be a direct consequence of the ability to draw the line between P-critical and P-high issues. There shouldn’t be too many P-critical issues that compiler meetings become unmanageable, but critical issues shouldn’t get lost in the list of P-high issues.

P-high issues are issues the teams will mostly work on. We want to make sure they’re assigned, and keep an eye on them. They are routinely reviewed in batches by the compiler team, deciding a possible priority downgrade.

P-medium and P-low

P-medium refer to issues that aren’t a priority for the team, and that will be resolved in the long run. For example, issues that will be fixed after a specific feature has landed. They are issues that the team could mentor someone interested in fixing. They will remain in this state until someone complains, a community member fixes it, or it gets fixed by accident.

P-low refer to issues issue that the compiler team doesn’t plan to resolve, but are still worth fixing. Nominate the issue if it’s unclear and needs to be discussed.

Generating the triage meeting agenda

The triage meeting agenda is generated automatically using the prioritization efforts as input. It is generated from a template available on HackMD or GitHub.

First, ensure that relevant issues are labelled as T-compiler..

• Issues labeled with I-prioritize
• Pull requests nominated for the stable release channel backport
• Pull requests nominated for the beta release channel backport
• Issues labeled I-compiler-nominated (i.e. needing a T-compiler discussion)
• Pull requests waiting on a team’s feedback
• Issues classified with priority P-high

..and that prioritization has been completed. Regressions labeled with I-prioritize are signaling that a priority assessment is waiting. When this label is added to an issue, the triagebot creates automatically a notification for @WG-prioritization members on the #t-compiler/prioritization/alerts Zulip channel.

To assign a priority, replace the I-prioritize label with one of P-critical, P-high, P-medium or P-low and adding a succinct comment to link the Zulip discussion where the issue prioritization occurred, example of a template for the comment:

Assigning priority (discussion on Zulip).

@rustbot label -I-prioritize +P-XXX

Tip: use Github Saved Replies to create a template comment.

Ideally, all T-compiler issues with a I-prioritize label to have a priority assigned, or strive to reach this goal: sometimes different factors are blocking issues from being assigned a priority label, either because the report or the context is unclear or because cannot be reproduced and an MCVE would help. Don’t hesitate to ask for clarifications to the issue reporter or ping the ICEbreaker team when an ICE (“Internal Compiler Errors”) needs a reduction (add a comment on the issue with @rustbot ping icebreakers-cleanup-crew)

Review stable, beta and nightly and try to ensure they are assigned when possikle.

The final step prior to generating the agenda is to accept any MCPs. Any MCPs that have had the final-comment-period label for more than ten days can be accepted. Remove the final-comment-period label and add the major-change-accepted label and then close the issue.

Finally, the meeting agenda can be generated. Clone and build triagebot and set the GITHUB_TOKEN environment variable with a GitHub API token.

Then generate the agenda with:

$ cargo run --bin prioritization-agenda

Copy the content into a new HackMD in the “Rust Lang Compiler Team” space. Copy the most recent performance triage logs and remove anything that won’t display well in Zulip

Add additional manual details to the agenda:

• Add summaries of stable/beta nominations (e.g. who nominated the backport and why)
• Add summaries of PRs waiting on the team (i.e. why are they waiting)
• Add initial impressions of P-critical/P-high bugs
• Add summaries of nominated issues (e.g. who the assignee is, why it was nominated, etc)
• Populate the oldest PRs waiting on review
  • Use judgement to determine whether a ping is appropriate (e.g. if the pull request is an experiment, it may not need a review; how long has it been since review activity; what do recent comments say?)

About two hours prior to the meeting, announce and share the completed agenda in the Zulip thread for the upcoming meeting (creating it if it does not already exist):

Hello @*T-compiler/meeting*, triage meeting in about 2h.
Pre-triage done in #**t-compiler/prioritization/alerts**.
Meeting agenda [on HackMD](https://hackmd.io/link_to_hackmd_agenda)

It is always recommended to re-run the generator and copy any new details over to the agenda as issue statuses on GitHub may have changed.

After the meeting, there are a few closing tasks:

• Lock the agenda on HackMD assigning write permissions to Owners. Download the Markdown file and commit the agenda as minutes to the compiler-team repository.
• Remove the to-announce label from MCPs, unless this label was added exactly during the meeting (and therefore will be seen during the following meeting).
• Remove to-announce FCPs from [rust-lang/rust repo][announce], compiler-team repo and forge repo. Same disclaimer as before regarding changes during the meeting.
• Accept or decline beta nominated and stable nominated backports that have been accepted during the meeting. For more info check [t-release backporting docs][release_backports]
  • To accept a backport, add a {beta,stable}-accepted label and keep the {beta,stable}-nominated label. Other automated procedures will process these pull requests, it’s important to leave both labels. Add a comment on Github linking the Zulip discussion.
  • To decline a backport, simply remove {beta,stable}-nominated label. Add a comment on Github explaining why the backport was declined and link the Zulip discussion.
• Remove I-compiler-nominated label from issues that were discussed. Sometimes not all nominated issues are discussed (because of time constraints). In this example, the I-compiler-nominated will stick until next meeting. Create a new agenda stub for the following.

Working Areas

Much of the ongoing work and initiatives from the compiler team are performed by groups of people interested in specific areas of work. These groups are a great way for new contributors to get involved as they provide a stream of tasks focused around one area and have designated channels for help and advice. Here is a list of areas where work is being carried on:

For historical record here’s a list of Working Groups that are not active anymore (either because they reached their goals or because work stalled):

Operations

“Operations” is a part of the Compiler Team that takes care of organizational and maintenance work and in general help things moving forward. T-compiler ops lives on Zulip under #t-compiler/ops.

Here is a list of recurring tasks. Ideally run through this list every week. If there are blockers or doubts, after having acquired the right context, don’t hesitate to ping people around. Contributors are the best resource of the project (and we want to be mindful of their time) and are always helpful.

You can trigger a discussion about a specific topic, issue or pull request by opening a new topic on Zulip in #t-compiler or, if it needs consensus and more focus from the team, it can can be labeled I-compiler-nominated and will be discussed in a meeting (see section Meetings).

Issues hygiene

• Issue to be prioritized: see prioritization.
• P-high issues without assignee: ideally this category of issues should have an assignee (filter out those without a PR).In rare cases it’s fine if they don’t.
• MCP in FCP status, close seconded since more 10 days, ensure no open concerns
• Check open MCPs: MCP is a protocol to bring proposals to the compiler team attention. Ensure MCPs are moving towards one of these two outcome, being seconded or being closed for lack of seconding. When it’s clear that an MCP won’t be seconded or is abandoned, after about two or three months is ok to query its status and evaluate closing it. Otherwise try to get them unstuck.
• Issues needing a reproducible
• Issues and PRs that are going through FCP: check if the team need to check their box. These issues are in the weekly triage agenda.

Prioritization for T-compiler

Some useful filters when looking at regressions.

• Nightly regressions without priority
• Beta regressions without priority
• Stable regressions without priority
• Untriaged regressions without a priority

PRs hygiene

• Every PR should have a team assigned
  • PR without a team label
  • Waiting on author
  • Waiting on a review

Things to do a week before the release:

• No regression without priority: ensure they’ve been fixed and if not try to get the team attention.
• No beta regressions or stable regressions regressions without an owner, filter out those out without a PR.
• No beta regressions or stable regressions regressions work in progress, ideally they should all be merged.
• Ensure breaking changes (i.e. regressions agreed to be acceptable) have a corresponding issue tagged relnotes-tracking-issue, see list of release notes. T-release will then pick them up and add them to the release notes.

After the release

• Check carefully which regressions can be closed as “accepted”. Add a comment clarifying that the PR causing the regression is accepted as breaking change, example: “Closing since PR #123456 will be mentioned in the release notes”. Discussions and comments about this practice can be directed on Zulip.

Meetings

T-compiler has two kinds of meetings: triage and design meetings. Triage meetings happen weekly, there is a tool to generate 80% of the meeting’s agenda. Design meetings proposals are advanced on the T-compiler repository and scheduled during recurrent steering meetings (where the next design meetings are scheduled). Design meetings also need an agenda and a bit of work to summarize the topic and bring together documentation, invite relevant people and so on.

Rest of the world

These filters are for checking what’s happening in other teams

• List of open RFCs (all teams) waiting for the team to discuss or check the proposal, can anything be done to help moving them forward?

crates.io

This section documents the processes of the crates.io team.

Crate removal procedure

If we get a DMCA takedown notice, here’s what needs to happen:

Contact Legal

Before removing the crates, get in touch with legal support, and ask an opinion from them on the received request and whether we have to comply with it.

Remove relevant version(s) and/or entire crates from crates.io

• Remove it from the database:

  heroku run -a crates-io -- target/release/crates-admin delete-crate [crate-name]
  

  or

  heroku run -a crates-io -- target/release/crates-admin delete-version [crate-name] [version-number]
  

• Remove the crate or version from the index. To remove an entire crate, remove the entire crate file. For a version, remove the line corresponding to the relevant version.

• Remove the crate archive(s) and readme file(s) from S3.

• Invalidate the CloudFront cache:

  aws cloudfront create-invalidation --distribution-id EJED5RT0WA7HA --paths '/*'
  

Remove entire crates from docs.rs

The docs.rs application supports deleting all the documentation ever published of a crate, by running a CLI command. The people who currently have permissions to access the server and run it are:

• docs.rs Team:
  • @pietroalbini
  • @jyn514
• Infrastructure Team:
  • @Mark-Simulacrum
• People with elevated 1password access

You can find the documentation on how to run the command here.

Database maintenance

There are times when Heroku needs to perform a maintenance on our database instances, for example to apply system updates or upgrade to a newer database server.

We must not let Heroku run maintenances during the maintenance window to avoid disrupting production users (move the maintenance window if necessary). This page contains the instructions on how to perform the maintenance with the minimum amount of disruption.

Primary database

Performing maintenance on the primary database requires us to temporarily put the application in read-only mode. Heroku performs maintenances by creating a hidden database follower and switching over to it, so we need to prevent writes on the primary to let the follower catch up.

Maintenance should take less than 5 minutes of read-only time, but we should still announce it ahead of time on our status page. This is a sample message we can use:

The crates.io team will perform a database maintenance on YYYY-MM-DD from hh:mm to hh:mm UTC.

We expect this to take less than 5 minutes to complete. During maintenance, crates.io will only be available in read-only mode: downloading crates and visiting the website will still work, but logging in, publishing crates, yanking crates, or changing owners will not work.

Primary database checklist

1 hour before the maintenance

1. Go into the Heroku Scheduler and disable the job enqueueing the downloads count updater. You can “disable” it by changing its schedule not to run during the maintenance window. The job uses a lot of database resources, and we should not run it during maintenance.

5 minutes before the maintenance

2. Scale the background worker to 0 instances:

   heroku ps:scale -a crates-io background_worker=0
   

At the start of the maintenance

3. Update the status page with this message:

   Scheduled maintenance on our database is starting.

   We expect this to take less than 5 minutes to complete. During maintenance, crates.io will only be available in read-only mode: downloading crates and visiting the website will still work, but logging in, publishing crates, yanking crates, or changing owners will not work.

4. Configure the application to be in read-only mode without the follower:

   heroku config:set -a crates-io READ_ONLY_MODE=1 DB_OFFLINE=follower
   

   The follower is removed because while Heroku tries to prevent connections to the primary database from failing during maintenance we observed that the same does not apply to the follower database, and there could be brief periods while the follower is not available.

5. Wait for the application to be redeployed with the new configuration:

   heroku ps:wait -a crates-io
   

6. Run the database maintenance:

   heroku pg:maintenance:run --force -a crates-io
   

7. Wait for the maintenance to finish:

   heroku pg:wait -a crates-io
   

8. Confirm all the databases are online:

   heroku pg:info -a crates-io
   

9. Confirm the primary database fully recovered (should output false):

   echo "SELECT pg_is_in_recovery();" | heroku pg:psql -a crates-io DATABASE
   

10. Switch off read-only mode:

    heroku config:unset -a crates-io READ_ONLY_MODE
    

    WARNING: the Heroku Dashboard’s UI is misleading when removing an environment variable. A red badge with a “-” (minus) in it means the variable was successfully removed, it doesn’t mean removing the variable failed. Failures are indicated with a red badge with a “x” (cross) in it.

11. Wait for the application to be redeployed with the new configuration:

    heroku ps:wait -a crates-io
    

12. Update the status page and mark the maintenance as completed with this message:

    Scheduled maintenance finished successfully.

    The message is posted right now and not at the end because this is when production users are not impacted by the maintenance anymore.

13. Scale the background worker up again:

    heroku ps:scale -a crates-io background_worker=1
    

14. Confirm the follower database is available:

    echo "SELECT 1;" | heroku pg:psql -a crates-io READ_ONLY_REPLICA
    

15. Enable connections to the follower:

    heroku config:unset -a crates-io DB_OFFLINE
    

16. Re-enable the background job disabled during step 1.

Follower database

Performing maintenance on the follower database doesn’t require any external communication nor putting the application in read-only mode, as we can just redirect all of the follower’s traffic to the primary database. It shouldn’t be done during peak traffic periods though, as we’ll increase the primary database load by doing this.

Follower database checklist

At the start of the maintenance

1. Configure the application to operate without the follower:

   heroku config:set -a crates-io DB_OFFLINE=follower
   

2. Wait for the application to be redeployed with the new configuration:

   heroku ps:wait -a crates-io
   

3. Start the database maintenance:

   heroku pg:maintenance:run --force -a crates-io READ_ONLY_REPLICA
   

4. Wait for the maintenance to finish:

   heroku pg:wait -a crates-io READ_ONLY_REPLICA
   

5. Confirm the follower database is ready:

   heroku pg:info -a crates-io
   

6. Confirm the follower database is responding to queries:

   echo "SELECT 1;" | heroku pg:psql -a crates-io READ_ONLY_REPLICA
   

7. Enable connections to the follower:

   heroku config:unset -a crates-io DB_OFFLINE
   

8. Wait for the application to be redeployed with the new configuration.

   heroku ps:wait -a crates-io
   

docs.rs

docs.rs is a website that hosts documentation for crates published to crates.io.

External Links

• Source code: rust-lang/docs.rs
• Hosted on: docsrs.infra.rust-lang.org (behind the bastion – how to connect)
• Maintainers: docs.rs team
• Instance metrics (only available to infra team members).
• Application metrics (only available to infra team members).

Add a dependency to the build environment

Rustwide internally uses rust-lang/crates-build-env as the build environment for the crate. If you want to add a system package for crates to link to, this is place you’re looking for.

Preconditions

Docker and docker-compose must be installed. For example, on Debian or Ubuntu:

sudo apt-get install docker.io docker-compose

Getting started

First, clone the crates-build-env and the docs.rs repos:

git clone https://github.com/rust-lang/crates-build-env
git clone https://github.com/rust-lang/docs.rs

Set the path to the directory of your crate. This must be an absolute path, not a relative path! On platforms with coreutils, you can instead use $(realpath ../relative/path) (relative to the docs.rs directory).

YOUR_CRATE=/path/to/your/crate

Add package

Next, add the package to crates-build-env/linux/packages.txt in the correct alphabetical order. This should be the name of a package in the Ubuntu 20.04 Repositories. See the package home page for a full list/search bar, or use apt search locally.

Building the image

Now build the image. This will take a very long time, probably 10-20 minutes.

cd crates-build-env/linux
docker build --tag build-env .

Testing the image

Use the image to build your crate.

cd ../../docs.rs
cp .env.sample .env
docker-compose build
# avoid docker-compose creating the volume if it doesn't exist
if [ -e "$YOUR_CRATE" ]; then
  docker-compose run -e DOCSRS_DOCKER_IMAGE=build-env \
                     -e RUST_BACKTRACE=1 \
                     -v "$YOUR_CRATE":/opt/rustwide/workdir \
    web build crate --local /opt/rustwide/workdir
else
  echo "$YOUR_CRATE does not exist";
fi

Making multiple changes

If your build fails even after your changes, it will be annoying to rebuild the image from scratch just to add a single package. Instead, you can make changes directly to the Dockerfile so that the existing packages are cached. Be sure to move these new packages from the Dockerfile to packages.txt once you are sure they work.

On line 7 of the Dockerfile, add this line: RUN apt-get install -y your_second_package. Rerun the build and start the container; it should take much less time now:

cd ../crates-build-env/linux
docker build --tag build-env .
cd ../../docs.rs
docker-compose run -e DOCSRS_DOCKER_IMAGE=build-env \
                     -e RUST_BACKTRACE=1 \
                     -v "$YOUR_CRATE":/opt/rustwide/workdir \
    web build crate --local /opt/rustwide/workdir

Run the lint script

Before you make a PR, run the shell script lint.sh and make sure it passes. It ensures packages.txt is in order and will tell you exactly what changes you need to make if not.

cd ../crates-build-env
./lint.sh

Make a pull request

Once you are sure your package builds, you can make a pull request to get it adopted upstream for docs.rs and crater. Go to https://github.com/rust-lang/crates-build-env and click ‘Fork’ in the top right. Locally, add your fork as a remote in git and push your changes:

git remote add personal https://github.com/<your_username_here>/crates-build-env
git add -u
git commit -m 'add packages necessary for <your_package_here> to compile'
git push personal

Back on github, make a pull request:

1. Go to https://github.com/rust-lang/crates-build-env/compare
2. Click ‘compare across forks’
3. Click ‘head repository’ -> <your_username>/crates-build-env
4. Click ‘Create pull request’
5. Add a description of what packages you added and what crate they fixed
6. Click ‘Create pull request’ again in the bottom right.

Hopefully your changes will be merged quickly! After that you can either publish a point release (rebuilds your docs immediately) or request for a member of the docs.rs team to schedule a new build (may take a while depending on their schedules).

Self hosting a docs.rs instance

These are instructions for deploying the server in a production environment. For instructions on developing locally without docker-compose, see Developing without docker-compose.

Here is a breakdown of what it takes to turn a regular server into its own version of docs.rs.

Beware: This process is rather rough! Attempts at cleaning it up, automating setup components, etc, would be greatly appreciated!

Requirements

The commands and package names on this page will assume an Ubuntu server running systemd, but hopefully the explanatory text should give enough information to adapt to other systems. Note that docs.rs depends on the host being x86_64-unknown-linux-gnu.

Docs.rs has a few basic requirements:

• Rust (preferably via rustup)
• Git
• CMake, GCC, G++, and pkg-config (to build dependencies for crates and docs.rs itself)
• OpenSSL, zlib, curl, and libmagic (to link against)
• PostgreSQL
• LXC tools (doc builds run inside an LXC container)

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain nightly
$ source $HOME/.cargo/env
# apt install build-essential git curl cmake gcc g++ pkg-config libmagic-dev libssl-dev zlib1g-dev postgresql lxc-utils

The cratesfyi user

To help things out later on, we can create a new unprivileged user that will run the server process. This user will own all the files required by the docs.rs process. This user will need to be able to run lxc-attach through sudo to be able to run docs builds, so give it a sudoers file at the same time:

# adduser --disabled-login --disabled-password --gecos "" cratesfyi
# echo 'cratesfyi  ALL=(ALL) NOPASSWD: /usr/bin/lxc-attach' > /etc/sudoers.d/cratesfyi

(The name cratesfyi is a historical one: Before the site was called “docs.rs”, it was called “crates.fyi” instead. If you want to update the name of the user, feel free! Just be aware that the name cratesfyi will be used throughout this document.)

The “prefix” directory

In addition to the LXC container, docs.rs also stores several related files in a “prefix” directory. This directory can be stored anywhere, but the cratesfyi user needs to be able to access it:

# mkdir /cratesfyi-prefix
# chown cratesfyi:cratesfyi /cratesfyi-prefix

Now we can set up some required folders. To make sure they all have proper ownership, run them all as cratesfyi:

$ sudo -u cratesfyi mkdir -vp /cratesfyi-prefix/documentations /cratesfyi-prefix/public_html /cratesfyi-prefix/sources
$ sudo -u cratesfyi git clone https://github.com/rust-lang/crates.io-index.git /cratesfyi-prefix/crates.io-index
$ sudo -u cratesfyi git --git-dir=/cratesfyi-prefix/crates.io-index/.git branch crates-index-diff_last-seen

(That last command is used to set up the crates-index-diff crate, so we can start monitoring new crate releases.)

LXC container

To help contain what crates’ build scripts can access, documentation builds run inside an LXC container. To create one inside the prefix directory:

# LANG=C lxc-create -n cratesfyi-container -P /cratesfyi-prefix -t download -- --dist ubuntu --release bionic --arch amd64
# ln -s /cratesfyi-prefix/cratesfyi-container /var/lib/lxc
# chmod 755 /cratesfyi-prefix/cratesfyi-container
# chmod 755 /var/lib/lxc

(To make deployment simpler, it’s important that the OS the container is using is the same as the host! In this case, the host is assumed to be running 64-bit Ubuntu 18.04. If you make the container use a different release or distribution, you’ll need to build docs.rs separately inside the container when deploying.)

You’ll also need to configure networking for the container. The following is a sample /etc/default/lxc-net that enables NAT networking for the container:

USE_LXC_BRIDGE="true"
LXC_BRIDGE="lxcbr0"
LXC_ADDR="10.0.3.1"
LXC_NETMASK="255.255.255.0"
LXC_NETWORK="10.0.3.0/24"
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"
LXC_DHCP_MAX="253"
LXC_DHCP_CONFILE=""
LXC_DOMAIN=""

In addition, you’ll need to set the container’s configuration to use this. Add the following lines to /cratesfyi-prefix/cratesfyi-container/config:

lxc.net.0.type = veth
lxc.net.0.link = lxcbr0

Now you can reload the LXC network configuration, start up the container, and set it up to auto-start when the host boots:

# systemctl restart lxc-net
# systemctl enable lxc@cratesfyi-container.service
# systemctl start lxc@cratesfyi-container.service

Now we need to do some setup inside this container. You can either copy all these commands so that each one attaches on its own, or you can run lxc-console -n cratesfyi-container to open a root shell inside the container and skip the lxc-attach prefix.

# lxc-attach -n cratesfyi-container -- apt update
# lxc-attach -n cratesfyi-container -- apt upgrade
# lxc-attach -n cratesfyi-container -- apt install curl ca-certificates binutils gcc libc6-dev libmagic1 pkg-config build-essential

Inside the container, we also need to set up a cratesfyi user, and install Rust for it. In addition to the base Rust installation, we also need to install all the default targets so that we can build docs for all the Tier 1 platforms. The Rust compiler installed inside the container is the one that builds all the docs, so if you want to use a new Rustdoc feature, this is the compiler to update.

lxc-attach -n cratesfyi-container -- adduser --disabled-login --disabled-password --gecos "" cratesfyi
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain nightly'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-apple-darwin'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-pc-windows-msvc'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add i686-unknown-linux-gnu'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add x86_64-apple-darwin'
lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup target add x86_64-pc-windows-msvc'

Now that we have Rust installed inside the container, we can use a trick to give the cratesfyi user on the host the same Rust compiler as the container. By symlinking the following directories into its user directory, we don’t need to track a third toolchain.

for directory in .cargo .rustup .multirust; do  [[ -h /home/cratesfyi/$directory ]] || sudo -u cratesfyi ln -vs /var/lib/lxc/cratesfyi-container/rootfs/home/cratesfyi/$directory /home/cratesfyi/; done

Environment for the cratesfyi user

To ensure that the docs.rs server is configured properly, we need to set a few environment variables. The primary ones are going into a separate environment file, so we can load them into the systemd service that will manage the server.

Write the following into /home/cratesfyi/.cratesfyi.env. If you have a GitHub access token that the site can use to collect repository information, add it here, but otherwise leave it blank. The variables need to exist, but they can be blank to skip that collection.

CRATESFYI_PREFIX=/cratesfyi-prefix
CRATESFYI_DATABASE_URL=postgresql://cratesfyi:password@localhost
CRATESFYI_CONTAINER_NAME=cratesfyi-container
CRATESFYI_GITHUB_USERNAME=
CRATESFYI_GITHUB_ACCESSTOKEN=
RUST_LOG=cratesfyi

Now add the following to /home/cratesfyi/.profile:

export $(cat $HOME/.cratesfyi.env | xargs -d '\n')
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$PATH:$HOME/docs.rs/target/release"

Docs.rs build

Now we can actually clone and build the docs.rs source! The location of it doesn’t matter much, but again, we want it to be owned by cratesfyi so it can build and run the final executable. In addition, we copy the built cratesfyi binary into the container so that it can be used to arrange builds on the inside.

sudo -u cratesfyi git clone https://github.com/rust-lang-nursery/docs.rs.git ~cratesfyi/docs.rs
sudo su - cratesfyi -c 'cd ~/docs.rs && cargo build --release'
cp -v /home/cratesfyi/docs.rs/target/release/cratesfyi /var/lib/lxc/cratesfyi-container/rootfs/usr/local/bin

PostgreSQL

Now that we have the repository built, we can use it to set up the database. Docs.rs uses a Postgres database to store information about crates and their documentation. To set one up, we first need to ask Postgres to create the database, and then run the docs.rs command to create the initial tables and content:

sudo -u postgres sh -c "psql -c \"CREATE USER cratesfyi WITH PASSWORD 'password';\""
sudo -u postgres sh -c "psql -c \"CREATE DATABASE cratesfyi OWNER cratesfyi;\""
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database init"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build add-essential-files"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build crate rand 0.5.5"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database update-search-index"
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- database update-release-activity"

Server configuration

We’re almost there! At this point, we’ve got all the pieces in place to run the site. Now we can set up a systemd service that will run the daemon that will collect crate information, orchestrate builds, and serve the website. The following systemd service file can be placed in /etc/systemd/system/cratesfyi.service:

[Unit]
Description=Cratesfyi daemon
After=network.target postgresql.service

[Service]
User=cratesfyi
Group=cratesfyi
Type=forking
PIDFile=/cratesfyi-prefix/cratesfyi.pid
EnvironmentFile=/home/cratesfyi/.cratesfyi.env
ExecStart=/home/cratesfyi/docs.rs/target/release/cratesfyi daemon
WorkingDirectory=/home/cratesfyi/docs.rs

[Install]
WantedBy=multi-user.target

Enabling and running that will serve the website on http://localhost:3000, so if you want to route public traffic to it, you’ll need to set up something like nginx to proxy the connections to it.

Updating Rust

If you want to update the Rust compiler used to build crates (and the Rustdoc that comes with it), you need to make sure you don’t interrupt any existing crate builds. The daemon waits for 60 seconds between checking for new crates, so you need to make sure you catch it during that window. Since we hooked the daemon into systemd, the logs will be available in its journal. Running journalctl -efu cratesfyi (it may need to be run as root if nothing appears) will show the latest log output and show new entries as they appear. You’re looking for a message like “Finished building new crates, going back to sleep” or “Queue is empty, going back to sleep”, which indicates that the crate-building thread is waiting.

To prevent the queue from building more crates, run the following:

sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build lock"

This will create a lock file in the prefix directory that will prevent more crates from being built. At this point, you can update the rustc inside the container and add the rustdoc static files to the database:

lxc-attach -n cratesfyi-container -- su - cratesfyi -c 'rustup update'
sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build add-essential-files"

Once this is done, you can unlock the queue to allow crates to build again:

sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build unlock"

And we’re done! New crates will start being built with the new rustc. If you want to rebuild any existing docs with the new rustdoc, you need to manually build them - there’s no automated way to rebuild failed docs or docs from a certain rust version yet.

Updating docs.rs

To update the code for docs.rs itself, you can follow a similar approach. First, watch the logs so you can stop the daemon from building more crates. (You can replace the lock command with a systemctl stop cratesfyi if you don’t mind the web server being down while you build.)

# journalctl -efu cratesfyi
(wait for build daemon to sleep)
$ sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build lock"

Once the daemon has stopped, you can start updating the code and rebuilding:

$ sudo su - cratesfyi -c "cd ~/docs.rs && git pull"
$ sudo su - cratesfyi -c "cd ~/docs.rs && cargo build --release"

Now that we have a shiny new build, we need to make sure the service is using it:

# cp -v /home/cratesfyi/docs.rs/target/release/cratesfyi /var/lib/lxc/cratesfyi-container/rootfs/usr/local/bin
# systemctl restart cratesfyi

Next, we can unlock the builder so it can start checking new crates:

$ sudo su - cratesfyi -c "cd ~/docs.rs && cargo run --release -- build unlock"

And we’re done! Changes to the site or the build behavior should be visible now.

Common maintenance procedures

Temporarily remove a crate from the queue

It might happen that a crate fails to build repeatedly due to a docs.rs bug, clogging up the queue and preventing other crates to build. In this case it’s possible to temporarily remove the crate from the queue until the docs.rs’s bug is fixed. To do that, log into the machine and open a PostgreSQL shell with:

$ psql

Then you can run this SQL query to remove the crate:

UPDATE queue SET attempt = 100 WHERE name = '<CRATE_NAME>';

To add the crate back in the queue you can run in the PostgreSQL shell this query:

UPDATE queue SET attempt = 0 WHERE name = '<CRATE_NAME>';

Pinning a version of nightly

Sometimes the latest nightly might be broken, causing doc builds to fail. In those cases it’s possible to tell docs.rs to stop updating to the latest nightly and instead pin a specific release. To do that you need to edit the /home/cratesfyi/.docs-rs-env file, adding or changing this environment variable:

CRATESFYI_TOOLCHAIN=nightly-YYYY-MM-DD

Once the file changed docs.rs needs to be restarted:

systemctl restart docs.rs

To return to the latest nightly simply remove the environment variable and restart docs.rs again.

Rebuild a specific crate

If a bug was recently fixed, you may want to rebuild a crate so that it builds with the latest version. From the docs.rs machine:

cratesfyi queue add <crate> <version>

This will add the crate with a lower priority than new crates by default, you can change the priority with the -p option.

Raise the limits for a specific crate

Occasionally crates will ask for their build limits to be raised. You can raise them from the docs.rs machine with psql.

Raising a memory limit to 8 GB:

# memory is measured in bytes
cratesfyi=> INSERT INTO sandbox_overrides (crate_name, max_memory_bytes)
  VALUES ('crate name', 8589934592);

Raising a timeout to 15 minutes:

cratesfyi=> INSERT INTO sandbox_overrides (crate_name, timeout_seconds)
  VALUES ('crate name', 900);

Raising limits for multiple crates at once:

cratesfyi=> INSERT INTO sandbox_overrides (crate_name, max_memory_bytes)
  VALUES ('stm32f4', 8589934592), ('stm32h7', 8589934592), ('stm32g4', 8589934592);

Set a group of crates to be automatically de-prioritized

When many crates from the same project are published at once, they take up a lot of space in the queue. You can de-prioritize groups of crates at once like this:

cratesfyi=> INSERT INTO crate_priorities (pattern, priority)
  VALUES ('group-%', 1);

The pattern should be a LIKE pattern as documented on https://www.postgresql.org/docs/current/functions-matching.html.

Note that this only sets the default priority for crates with that name. If there are crates already in the queue, you’ll have to update those manually:

cratesfyi=> UPDATE queue SET priority = 1 WHERE name LIKE 'group-%';

Adding all the crates failed after a date back in the queue

After an outage you might want to add all the failed builds back to the queue. To do that, log into the machine and open a PostgreSQL shell with:

psql

Then you can run this SQL query to add all the crates failed after YYYY-MM-DD HH:MM:SS back in the queue:

UPDATE queue SET attempt = 0 WHERE attempt >= 5 AND build_time > 'YYYY-MM-DD HH:MM:SS';

Removing a crate from the website

Sometimes it might be needed to remove all the content related to a crate from docs.rs (for example after receiving a DMCA). To do that, log into the server and run:

cratesfyi database delete-crate CRATE_NAME

The command will remove all the data from the database, and then remove the files from S3.

Blacklisting crates

Occasionally it might be needed to prevent a crate from being built on docs.rs, for example if we can’t legally host the content of those crates. To add a crate to the blacklist, preventing new builds for it, you can run:

cratesfyi database blacklist add <CRATE_NAME>

Other operations (such as list and remove) are also supported.

Warning: blacklisting a crate doesn’t remove existing content from the website, it just prevents new versions from being built!

Governance

Leadership Council

The Leadership Council is a representative group of the teams within the Rust Project, tasked with coordinating between teams and to ensure successful operation of the Rust Project.

The policies governing the Leadership Council are specified in the Leadership Council chapter.

Moderation

The Moderation team is responsible for dealing with violations of the Rust Code of Conduct.

The policies governing the Moderation team are specified in the Moderation chapter.

Leadership Council

This document defines the authority¹ and policies of the Rust Leadership Council (“Council”) to ensure successful operation of the Rust Project.

This document serves as a living document defining the current accepted set of policies governing the Council. The basis of this document started with the text of RFC 3392 which established the Council, and may be updated via the RFC process.

The Council delegates much of this authority to teams (which includes subteams, working groups, etc.²) who autonomously make decisions concerning their purviews. However, the Council retains some decision-making authority, outlined and delimited by this document.

The Council maintains a separate home site at https://github.com/rust-lang/leadership-council where they document their internal processes, and coordinate their work.

The Council is composed of representatives delegated to the Council from each top-level team.

The Council is charged with the success of the Rust Project as a whole. The Council identifies work that needs to be done but does not yet have a clear owner, creates new teams to accomplish this work, holds existing teams accountable for the work in their purview, and coordinates and adjusts the organizational structure of Project teams.

Outline

• Motivation
• Duties, expectations, and constraints on the Council
• Structure of the Council
  • Top-level teams
    • The Launching Pad top-level team
    • Removing top-level teams
  • Alternates and forgoing representation
  • Term limits
  • Limits on representatives from a single company/entity
  • Candidate criteria
  • Credentials
  • Relationship to the Rust Foundation
• The Council’s decision-making process
  • Operational vs policy decisions
  • Repetition and exceptions
  • The consent decision-making process
    • Approval criteria
  • Modifying and tuning the decision-making process
  • Agenda and backlog
  • Deadlock resolution
  • Feedback and evaluation
• Transparency and oversight for decision making
  • Decisions that the Council may make internally
  • Decisions that the Council must necessarily make privately
  • Decisions that the Council must make via public proposal
  • Conflicts of interest
  • Determining and changing team purviews
• Mechanisms for oversight and accountability
  • Ensuring the Council is accountable
  • Ensuring Council representatives are accountable
  • Ensuring teams are accountable
• Footnotes

Motivation

The Rust project consists of hundreds of globally distributed people, organized into teams with various purviews. However, a great deal of work falls outside the purview of any established team, and still needs to get done.

The Council focuses on identifying and prioritizing work outside of team purviews. The Council primarily delegates that work, rather than doing that work itself. The Council can also serve as a coordination, organization, and accountability body between teams, such as for cross-team efforts, roadmaps, and the long-term success of the Project.

Duties, expectations, and constraints on the Council

At a high-level, the Council is only in charge of the following duties:

• Identifying, prioritizing, and tracking work that goes undone due to lack of clear ownership (and not due to the owners’ explicit de-prioritization, placement in a backlog, etc.).
• Delegating this work, potentially establishing new (and possibly temporary) teams to own this work.
• Making decisions on urgent matters that do not have a clear owner.
  • This should only be done in exceptional circumstances where the decision cannot be delegated either to existing teams or to newly created ones.
• Coordinating Project-wide changes to teams, structures, or processes.
• Ensuring top-level teams are accountable to their purviews, to other teams, and to the Project.
• Ensuring where possible that teams have the people and resources they need to accomplish their work.
• Establishing the official position, opinion, or will of the Rust Project as a whole.
  • This helps reduce the need for Project-wide coordination, especially when a long public polling and consensus-building process is not practical - for example, when communicating with third parties who require some understanding of what the Rust Project as a whole “wants”.

In addition to these duties, the Council has additional expectations and constraints, to help determine if the Council is functioning properly:

• Delegate work: The Council should not take on work beyond what this document explicitly assigns to it; it must delegate to existing or new teams distinct from the Council. Such teams may include Council representatives, but such membership is not part of the duties of a Council representative.
• Ensure the Project runs smoothly in the long term: The Council should ensure that non-urgent Project management work is prioritized and completed with enough regularity that the Project does not accumulate organizational debt.
• Be Accountable: As the Council wields broad power, the Council and Council representatives must be accountable for their actions. They should listen to others’ feedback, and actively reflect on whether they continue to meet the duties and expectations of the position they hold.
• Be representational: Council representatives should not only represent the breadth of Project concerns but also the diversity of the Rust community in as many aspects as possible (demographics, technical background, etc).
• Share burden: All Council representatives must share burden of Council duties.
• Respect others’ purviews: The Council must respect the purviews delegated to teams. The Council should consult with and work together with teams on solutions to issues, and should almost never make decisions that go against the wishes of any given team.
• Act in good faith: Council representatives should make decisions in the best interest of the Rust Project as a whole even if those decisions come into conflict with their individual teams, their employers, or other outside interests.
• Be transparent: While not all decisions (or all aspects of a decision) can be made public, the Council should be as open and transparent about their decision-making as possible. The Council should also ensure the organizational structure of the Project is clear and transparent.
• Respect privacy: The Council must never compromise personal or confidential information for the sake of transparency, including adjacent information that could unintentionally disclose privileged information.
• Foster a healthy working environment: The Council representatives should all feel satisfied with the amount and nature of their contribution. They should not feel that their presence on the Council is merely out of obligation but rather because they are actively participating in a meaningful way.
• Evolve: The Council is expected to evolve over time to meet the evolving needs of teams, the Project, and the community.

Council representatives, moderation team members, and other Project members serve as examples for those around them and the broader community. All of these roles represent positions of responsibility and leadership; their actions carry weight and can exert great force within the community, and should be wielded with due care. People choosing to serve in these roles should thus recognize that those around them will hold them to a correspondingly high standard.

Structure of the Council

The Council consists of a set of team representatives, each representing one top-level team and its subteams.

Each top-level team designates exactly one representative, by a process of their choice.

Any member of the top-level team or a member of any of their subteams is eligible to be the representative. Teams should provide members of their subteams with an opportunity for input and feedback on potential candidates.

Each representative represents at most one top-level team, even if they’re also a member of other teams. The primary responsibility of representing any Rust team falls to the representative of the top-level team they fall under.³

All teams in the Rust Project must ultimately fall under at least one top-level team. The Launching Pad team serves as a temporary home for teams that do not currently have a parent team. This ensures that all teams have representation on the Council.

Top-level teams

The Council establishes top-level teams via public policy decisions. In general, top-level teams should meet the following criteria:

• Have a purview that is foundational to the Rust Project
• Be the ultimate decision-makers on all aspects of that purview
• Have a purview that not is a subset of another team’s purview (that is, it must not be a subteam or similar governance structure)
• Have an open-ended purview that’s expected to continue indefinitely
• Be a currently active part of the Rust Project

There must be between 4 and 9 top-level teams (inclusive), preferably between 5 and 8. This number balances the desire for a diverse and relatively shallow structure while still being practical for productive conversation and consent.⁴

When the Council creates a new top-level team, that team then designates a Council representative.⁵ When creating a new top-level team, the Council must provide justification for why it should not be a subteam or other governance structure.

The set of top-level teams is:

• Compiler
• Dev tools
• Infrastructure
• Language
• Launching Pad
• Library
• Moderation

The Launching Pad top-level team

The Launching Pad team temporarily accepts subteams that otherwise do not have a top-level team to slot underneath of. This ensures that all teams have representation on the Council, while more permanent parent teams are found or established.

The Launching Pad team is an umbrella team: it has no direct members, only subteam representatives.

The Council should work to find or create a more appropriate parent for each subteam of the Launching Pad, and subsequently move those subteams to their new parent team.

In some cases, an appropriate parent team may exist but not yet be ready to accept subteams; the Launching Pad can serve as an interim home in such cases.

The Launching Pad also serves as a default home for subteams of a team that’s removed or reorganized away, if that removal or reorganization does not explicitly place those subteams somewhere else in the organization.

The Council must review subteam membership in the Launching Pad every 6 months to ensure that proper progress is being made on finding all subteams new parent teams. As with other top-level teams, the Launching Pad team can be retired (and have its representation within the Council removed) if the Council finds it to be no longer necessary. The process for retiring the Launching Pad team is the same as with other top-level teams. Alternatively, the Council is free to give the Launching Pad team its own purview.

Removing top-level teams

Any decision to remove a team’s top-level designation (or otherwise affect eligibility for the Council) requires the consent of all Council representatives, with the exception of the representative of the top-level team being removed. Despite this caveat, the representative of the team under consideration must be invited to Council deliberations concerning the team’s removal, and the Council should only remove a team over their objections in extreme cases.

The Council cannot remove the moderation team. The Council cannot change the moderation team’s purview without the agreement of the moderation team.

Alternates and forgoing representation

A representative may end their term early if necessary, such as due to changes in their availability or circumstances. The respective top-level team must then begin selecting a new representative. The role of representative is a volunteer position. No one is obligated to fill that role, and no team is permitted to make serving as a representative a necessary obligation of membership in a team. However, a representative is obligated to fulfill the duties of the position of representative, or resign that position.

A top-level team may decide to temporarily relinquish their representation, such as if the team is temporarily understaffed and they have no willing representative. However, if the team does not designate a Council representative, they forgo their right to actively participate in decision-making at a Project-wide level. All Council procedures including decision-making should not be blocked due to this omission. The Council is still obligated to consider new information and objections from all Project members. However, the Council is not obligated to block decisions to specially consider or collate a non-represented team’s feedback.

Sending a representative to the Council is considered a duty of a top-level team, and not being able to regularly do so means the team is not fulfilling its duties. However, a Council representative does not relinquish their role in cases of short absence due to temporary illness, vacation, etc.

A top-level team can designate an alternate representative to serve in the event their primary representative is unavailable. This alternate assumes the full role of Council representative until the return of the primary representative. Alternate representatives do not regularly attend meetings when the primary representative is present (to avoid doubling the number of attendees).

If a team’s representative and any alternates fail to participate in any Council proceedings for 3 consecutive weeks, the team’s representative ceases to count towards the decision-making quorum requirements of the Council until the team can provide a representative able to participate. The Council must notify the team of this before it takes effect. If a team wishes to ensure the Council does not make decisions without their input or without an ability for objections to be made on their behalf, they should ensure they have an alternate representative available.

A top-level team may change their representative before the end of their term, if necessary. However, as maintaining continuity incurs overhead, teams should avoid changing their representatives more than necessary. Teams have the primary responsibility for briefing their representative and alternates on team-specific issues or positions they wish to handle on an ongoing basis. The Council and team share the responsibilities of maintaining continuity for ongoing issues within the Council, and of providing context to alternates and other new representatives.

For private matters, the Council should exercise discretion on informing alternates, to avoid spreading private information unnecessarily; the Council can brief alternates if they need to step in.

Term limits

Council representatives’ terms are one year in length. Each representative has a soft limit of three consecutive full terms for any given representative delegation (the delegation from a particular top-level team). A representative may exceed this soft limit if and only if the Council receives explicit confirmation from the respective team that they are unable to produce a different team member as a representative (for example, due to lack of a willing alternative candidate, or due to team members having blocking objections to any other candidate).

Beyond this, there is no hard limit on the number of terms a representative can serve for other top-level teams or non-consecutive terms for a single top-level team. Teams should strive for a balance between continuity of experience and rotating representatives to provide multiple people with such experience.⁶

Half of the representative appointments shall happen at the end of March while half shall happen at the end of September. This avoids changing all Council representatives at the same time. For the initial Council, and anytime the set of top-level teams is changed, the Council and top-level teams should work together to keep term end-dates roughly evenly divided between March and September. However, each term should last for a minimum of 6 months (temporary imbalance is acceptable to avoid excessively short terms).

If the Council and top-level teams cannot agree on appropriate term end-date changes, representatives are randomly assigned to one or the other end date (at least 6 months out) to maintain balance.

Limits on representatives from a single company/entity

Council representatives must not disproportionately come from any one company, legal entity, or closely related set of legal entities, to avoid impropriety or the appearance of impropriety. If the Council has 5 or fewer representatives, no more than 1 representative may have any given affiliation; if the Council has 6 or more representatives, no more than 2 representatives may have any given affiliation.

Closely related legal entities include branches/divisions/subsidiaries of the same entity, entities connected through substantial ownership interests, or similar. The Council may make a judgment call in unusual cases, taking care to avoid conflicts of interest in that decision.

A Council representative is affiliated with a company or other legal entity if they derive a substantive fraction of their income from that entity (such as from an employer, client, or major sponsor). Representatives must promptly disclose changes in their affiliations.

If this constraint does not hold, whether by a representative changing affiliation, top-level teams appointing new representatives, or the Council size changing, restore the constraint as follows:

• Representatives with the same affiliation may first attempt to resolve the issue amongst themselves, such that a representative voluntarily steps down and their team appoints someone else.
  • This must be a decision by the representative, not their affiliated entity; it is considered improper for the affiliated entity to influence this decision.
  • Representatives have equal standing in such a discussion; factors such as seniority in the Project or the Council must not be used to pressure people.
• If the representatives with that affiliation cannot agree, one such representative is removed at random. (If the constraint still does not hold, the remaining representatives may again attempt to resolve the issue amongst themselves before repeating this.) This is likely to produce suboptimal results; a voluntary solution will typically be preferable.
• While a team should immediately begin the process of selecting a successor, the team’s existing representative may continue to serve up to 3 months of their remaining term.
• The existing representative should coordinate the transition with the incoming representative but it is the team’s choice which one is an actual representative during the up to 3 month window. There is only ever one representative from the top-level team.

Candidate criteria

The following are criteria for deciding ideal candidates. These are similar to but not the same as the criteria for an effective team lead or co-lead. While a team lead might also make a good Council representative, serving as a team lead and serving as a Council representative both require a substantial time investment, which likely motivates dividing those roles among different people. The criteria are not hard requirements but can be used for determining who is best positioned to be a team’s representative. In short, the representative should have:

• sufficient time and energy to dedicate to the needs of the Council.
• an interest in helping with the topics of Project operations and Project governance.
• broad awareness of the needs of the Project outside of their teams or areas of active contribution.
• a keen sense of the needs of their team.
• the temperament and ability to represent and center the needs of others above any personal agenda.
• ability and willingness to represent all viewpoints from their team, not just a subset, and not just those they agree with.

While some teams may not currently have an abundance of candidates who fit this criteria, the Council should actively foster such skills within the larger Project, as these are helpful not only for Council membership but across the entire Project.

Credentials

The Council does not have privileged access to administrative credentials for the project. This access solely resides with the infrastructure team⁷. The infrastructure team’s responsibilities include ensuring teams have the tools and access needed to do their work effectively, while balancing against security and maintainability of our infrastructure. The Council can help coordinate which teams should have access through policy.

Relationship to the Rust Foundation

The Council is responsible for establishing the process for selecting Project directors. The Project directors are the mechanism by which the Rust Project’s interests are reflected on the Rust Foundation board.

The Council delegates a purview to the Project directors to represent the Project’s interests on the Foundation Board and to make certain decisions on Foundation-related matters. The exact boundaries of that purview are not yet specified.

The Council’s decision-making process

The Council make decisions of two different types: operational decisions and policy decisions. Certain considerations may be placed on a given decision depending on its classification. However, by default, the Council uses a consent decision-making process for all decisions regardless of classification.

Operational vs policy decisions

Operational decisions are made on a daily basis by the Council to carry out their aims, including regular actions taking place outside of meetings (based on established policy). Policy decisions provide general reusable patterns or frameworks, meant to frame, guide, and support operations. In particular, policy decisions can provide partial automation for operational decisions or other aspects of operations. The council defaults to the consent decision making process for all decisions unless otherwise specified.

It is not defined precisely which decisions are operations versus policy; rather, they fall somewhere along a continuum. The purpose of this distinction is not to direct or constrain the council’s decision-making procedures. Instead, this distinction provides guidance to the Council, and clarifies how the Council intends to record, review, and refine its decisions over time. For the purposes of any requirements or guidance associated with the operational/policy classification, anything not labeled as either operational or policy in this or future policy defaults to policy.

Repetition and exceptions

Policy decisions often systematically address what might otherwise require repeated operational decisions. The Council should strive to recognize when repeated operational decisions indicate the need for a policy decision, or a policy change. In particular, the Council should avoid allowing repeated operational decisions to constitute de facto policy.

Exceptions to existing policy cannot be made via an operational decision unless such exceptions are explicitly allowed in said policy. Avoiding ad-hoc exceptions helps avoid “normalization of deviance”.

The consent decision-making process

Consent means that no representative’s requirements (and thus those of the top-level team and subteams they represent) can be disregarded. The Council hears all relevant input and sets a good foundation for working together equitably with all voices weighted equally.

The Council uses consent decision-making where instead of being asked “do you agree?”, representatives are asked “do you object?”. This eliminates “pocket vetoes” where people have fully reviewed a proposal but decide against approving it without giving clear feedback as to the reason. Concerns, feedback, preferences, and other less critical forms of feedback do not prevent making a decision, but should still be considered for incorporation earlier in drafting and discussion. Objections, representing an unmet requirement or need, must be considered and resolved to proceed with a decision.

Approval criteria

The consent decision-making process has the following approval criteria:

• Posting the proposal in one of the Council’s designated communication spaces (a meeting or a specific channel).
• Having confirmation that at least N-2 Council representatives (where N is the total number of Council representatives) have fully reviewed the final proposal and give their consent.
• Having no outstanding explicit objections from any Council representative.
• Providing a minimum 10 days for feedback.

The approval criteria provides a quorum mechanism, as well as sufficient time for representatives to have seen the proposal. Allowing for two non-signoffs is an acknowledgement of the volunteer nature of the Project, based on experience balancing the speed of decisions with the amount of confirmation needed for consent and non-objection; this assumes that those representatives have had time to object if they wished to do so. (This is modeled after the process used today for approval of RFCs.)

The decision-making process can end at any time if the representative proposing it decides to retract their proposal. Another representative can always adopt a proposal to keep it alive.

If conflicts of interest result in the Council being unable to meet the N-2 quorum for a decision, the Council cannot make that decision unless it follows the process documented in the “Conflicts of interest” section for how a decision may proceed with conflicts documented. In such a case, the Council should consider appropriate processes and policies to avoid future recurrences of a similar conflict.

Modifying and tuning the decision-making process

Using the public policy process, the Council can establish different decision-making processes for classes of decisions.

When deciding on which decision-making process to adopt for a particular class of decision, the Council balances the need for quick decisions with the importance of confidence in full alignment. Consent decision-making processes fall on the following spectrum:

• Consensus decision making (prioritizes confidence in full alignment at the expense of quick decision making): team members must review and prefer the proposal over all others, any team members may raise a blocking objection
• Consent decision making (default for the Council, balances quick decisions and confidence in alignment): team members must review and may raise a blocking objection
• One second and no objections (prioritizes quick decision making at the expense of confidence in alignment): one team member must review and support, any team member may raise a blocking objection

Any policy that defines decision-making processes must at a minimum address where the proposal may be posted, quorum requirements, number of reviews required, and minimum time delay for feedback. A lack of objections is part of the approval criteria for all decision-making processes.

If conflicts of interest prevent more than a third of the Council from participating in a decision, the Council cannot make that decision unless it follows the process documented in the “Conflicts of interest” section for how a decision may proceed with conflicts documented. (This is true regardless of any other quorum requirements for the decision-making process in use.) In such a case, the Council should consider appropriate processes and policies to avoid future recurrences of a similar conflict.

The Council may also delegate subsets of its own decision-making purviews via a public policy decision, to teams, other governance structures, or roles created and filled by the Council, such as operational lead, meeting facilitator, or scribe/secretary.

Note that the Council may delegate the drafting of a proposal without necessarily delegating the decision to approve that proposal. This may be necessary in cases of Project-wide policy that intersects the purviews of many teams, or falls outside the purview of any team. This may also help when bootstrapping a new team incrementally.

Agenda and backlog

The Council’s agenda and backlog are the primary interface through which the Council tracks and gives progress updates on issues raised by Project members throughout the Project.

To aid in the fairness and effectiveness of the agenda and backlog, the Council must:

• Use a tool that allows Project members to submit requests to the Council and to receive updates on those requests.
• Use a transparent and inclusive process for deciding on the priorities and goals for the upcoming period. This must involve regular check-ins and feedback from all representatives.
• Strive to maintain a balance between long-term strategic goals and short-term needs in the backlog and on the agenda.
• Be flexible and adaptable and be willing to adjust the backlog and agenda as needed in response to changing circumstances or priorities.
• Regularly review and update the backlog to ensure that it accurately reflects the current priorities and goals of the Council.
• Follow a clear and consistent process for moving items from the backlog to the agenda, such as delegating responsibility to roles (e.g. meeting facilitator and scribe), and consenting to the agenda at the start of meetings. Any agenda items rejected during the consent process must have their objections documented in the published meeting minutes of the Council.

Deadlock resolution

In some situations the Council might need to make an decision urgently and not feel it can construct a proposal in that time that everyone will consent to. In such cases, if everyone agrees that a timely decision they disagree with would be a better outcome than no timely decision at all, the Council may use an alternative decision-making method to attempt to resolve the deadlock. The alternative process is informal, and the council members must still re-affirm their consent to the outcome through the existing decision making process. Council members may still raise objections at any time.

For example, the Council can consent to a vote, then once the vote is complete all of the council members would consent to whatever decision the vote arrived to. The Council should strive to document the perceived advantages and disadvantages for choosing a particular alternative decision-making model.

There is, by design, no mandatory mechanism for deadlock resolution. If the representatives do not all consent to making a decision even if they don’t prefer the outcome of that decision, or if any representative feels it is still possible to produce a proposal that will garner the Council’s consent, they may always maintain their objections.

If a representative withdraws an objection, or consents to a decision they do not fully agree with (whether as a result of an alternative decision-making process or otherwise), the Council should schedule an evaluation or consider shortening the time until an already scheduled evaluation, and should establish a means of measuring/evaluating the concerns voiced. The results of this review are intended to determine whether the Council should consider changing its prior decision.

Feedback and evaluation

All policy decisions should have an evaluation date as part of the policy. Initial evaluation periods should be shorter in duration than subsequent evaluation periods. The length of evaluation periods should be adjusted based on the needs of the situation. Policies that seem to be working well and require few changes should be extended so less time is spent on unnecessary reviews. Policies that have been recently adjusted or called into question should have shortened evaluation periods to ensure they’re iterating towards stability more quickly. The Council should establish standardized periods for classes of policy to use as defaults when determining periods for new policy. For instance, roles could have an evaluation date of 3 months initially then 1 year thereafter, while general policy could default to 6 months initially and 2 years thereafter.

• New policy decisions can always modify or replace existing policies.
• Policy decisions must be published in a central location, with version history.
• Modifications to the active policy docs should include or link to relevant context for the policy decision, rather than expecting people to find that context later.

Transparency and oversight for decision making

Decisions made by the Council will necessarily require varying levels of transparency and oversight based on the kind of decision being made. This section gives guidance on how the Council will seek oversight for its decisions, and what qualifies decisions to be made in private or in public.

This RFC places certain decisions into each category. All decisions not specifically enumerated must use the public policy process. The Council may evolve the categorization through the public policy process.

Decisions made by the Council fall into one of three categories, based on the level of oversight possible and necessary:

• Decisions that the Council may make internally
• Decisions that the Council must necessarily make privately
• Decisions that the Council must make via public proposal

Decisions that the Council may make internally

Some types of operational decisions can be made internally by the Council, with the provision that the Council has a mechanism for community feedback on the decision after it has been made.

Adding a new decision to the list of decisions the Council can make internally requires a public policy decision. Any decisions that impact the structure, decision-makers, or oversight of the Council itself should not be added to this list.

The Council should also strive to avoid establishing de facto unwritten policy via repeated internal decisions in an effort to avoid public proposal. See “Repetition and exceptions” for more details.

This list exhaustively enumerates the set of decisions that the Council may make internally:

• Deciding to start a process that itself will play out in public (e.g. “let’s start developing and posting the survey”, “let’s draft an RFC for this future public decision”).
• Expressing and communicating an official position statement of the Rust Project.
• Expressing and communicating the position of the Rust Project directly to another entity, such as the Rust Foundation.
• Communicating via Rust Project communication resources (via the blog or all@).
• Making most operational decisions about the Council’s own internal processes, including how the Council coordinates, the platforms it uses to communicate, where and when it meets, templates used for making and recording decisions (subject to requirements elsewhere in this document).
• Appointing officers or temporary roles within the Council, for purposes such as leading/facilitating meetings, recording and publishing minutes, obtaining and collating feedback from various parties, etc.⁸ Note that any such roles (titles, duties, and current holders) must be publicly disclosed and documented.
• Inviting specific attendees other than Council representatives to specific Council meetings or discussions, or holding a meeting open to the broader community. (In particular, the Council is encouraged to invite stakeholders of a particular decision to meetings or discussions where said decision is to be discussed.)
• Making decisions requested by one or more teams that would be within the normal purviews of those teams to make without a public proposal. (Note that teams can ask for Council input without requesting a Council decision.)
• Making one-off judgment calls in areas where the purviews of teams overlap or are ambiguous (though changing the purviews of those teams must be a public policy decision).
• Any decision that this document or future Council policy specifies as an operational decision.

See the accountability section for details on the feedback mechanism for Council decisions.

Decisions that the Council must necessarily make privately

Some decisions necessarily involve private details of individuals or other entities, and making these details public would have a negative impact both on those individuals or entities (e.g. safety) and on the Project (eroding trust).

This additional constraint should be considered an exceptional case. This does not permit making decisions that would require a public proposal per the next section. However, this does permit decisions that the Council makes internally to be kept private, without full information provided for public oversight.

The Council may also decline to make a decision privately, such as if the Council considers the matter outside their purview (and chooses to defer to another team) or believes the matter should be handled publicly. However, even in such a case, the Council still cannot publicly reveal information shared with it in confidence (since otherwise the Council would not be trusted to receive such information). Obvious exceptions exist for imminent threats to safety.

Private decisions must not establish policy. The Council should also strive to avoid establishing de facto unwritten policy via repeated private decisions in an effort to avoid public proposal. See “Repetition and exceptions” for more details.

This list exhaustively enumerates the set of decisions that the Council may make either partly or entirely in private:

• Determining relationships with new industry / Open Source initiatives, that require confidentiality before launching.
• Discussing the personal aspects of a dispute between teams that involves some interpersonal dynamics/conflicts.
• Participating in contract negotiations on behalf of the Project with third parties (e.g. accepting resources provided to the Project).
• Decisions touching on Project-relevant controversial aspects of politics, personal safety, or other topics in which people may not be safe speaking freely in public.
• Discussing whether and why a team or individual needs help and support, which may touch on personal matters.
• Any decision that this document or future Council policy specifies as a private decision.

The Council may pull in members of other teams for private discussions leading to either a private or public decision, unless doing so would more broadly expose private information disclosed to the Council without permission. When possible, the Council should attempt to pull in people or teams affected by a decision. This also provides additional oversight.

Some matters may not be fit for full public disclosure while still being fine to share in smaller, more trusted circles (such as with all Project members, with team leads, or with involved/affected parties). The Council should strive to share information with the largest appropriate audiences for that information.

The Council may decide to withhold new decisions or aspects of decisions when it’s unclear whether the information is sensitive. However, as time progresses and it becomes clearer who the appropriate audience is or that the appropriate audience has expanded, the council should revisit its information-sharing decisions.

The Council should always loop in the moderation team for matters involving interpersonal conflict/dispute, both because such matters are the purview of the moderation team, and to again provide additional oversight.

The council should evaluate which portions of a decision or its related discussions necessarily need to be private, and should consider whether it can feasibly make non-sensitive portions public, rather than keeping an entire matter private just because one portion of it needs to be. This may include the existence of the discussion, or the general topic, if those details are not themselves sensitive.

Private matters may potentially be able to become public, or partially public, at a later date if they’re no longer sensitive. However, some matters may potentially never be able to become public, which means they will never become subject to broader review and oversight. Thus, the Council must exercise caution and prudence before making a private decision.

The Council should make every effort to not make private decisions. The Council should have appropriate additional processes in place to encourage representatives to collectively review such decisions and consider their necessity.

Decisions that the Council must make via public proposal

Decisions in this category require the Council to publicly seek feedback from the broader Rust Project in advance of the decision being made. Such decisions are proposed and decided via the appropriate public decision process, currently the RFC process (though the Council may adopt a different public proposal process in the future). The public decision process must require the consent of representatives (either affirmatively or via non-objection), must allow for blocking objections by Council representatives, must provide reasonable time for public evaluation and discussion, and must provide a clear path for public feedback to the Council.

Following the existing RFC process, public proposals must have a minimum time-delay for feedback before the decision takes effect. Any representative may request that the feedback period for a particular decision is extended to at most 20 days total. The Council may make an internal operational decision to extend the feedback period beyond 20 days. The time-delay for feedback starts only when the necessary threshold for approval is otherwise met, including there not being any raised objections. If objections are raised and resolved during the time-delay, the waiting period starts again.

The Council is expected to evolve over time to meet the evolving needs of the teams, the Rust Project, and the community. Such evolutionary changes may be small or large in scope and require corresponding amounts of oversight. Changes that materially impact the shape of the Council would need to be part of a public decision process.

As an exception to the above, modifications or removals of a single top-level team (other than the moderation team) may occur with the unanimous agreement of the Council absent the representative delegated by that top-level team.

The Council is permitted to have private discussions even on something that ultimately ends up as a public proposal or a publicly disclosed internal decision. The Council may wish to do this if the discussions are sensitive to allow decision participants to speak more frankly and freely. Additionally, in some cases, private information that can’t be disclosed may impact an otherwise public decision/proposal; the Council should strive to be as transparent and non-misleading as possible and avoid having opaque decisions where all rationale is private.

Note that all decisions fall into this category unless explicitly designated (via this document or future public proposals) to fall into another category, so this list (unlike those in the other two categories) is intentionally vague/broad: it is intended to give guidance on what likely should belong in this category without necessarily being prescriptive.

• Any decision that has the effect of modifying the list of decision-makers on the Council or the decision-making process of the Council. For instance:
  • Changing this list (or this document in general).
  • Modifying the publication and approval process used for the Council’s public proposals. Such a proposal must use the existing established process, not the proposed process.
  • Adding, modifying, or removing policies affecting eligibility for Council representatives.
  • Adding, modifying, or removing one or more top-level teams. This includes:
    • modifying the purview of a top-level team to such an extent that it meaningfully becomes a different team.
    • reorganizing the Project such that top-level teams move underneath other teams.
  • Adding other types of Council representatives other than those delegated by top-level teams.
  • Adding, modifying, or removing policies regarding Council quorums or the locations in which binding decisions can be made.
• Any policy decision, as opposed to a one-off operational decision. (See the decision-making section for details on policy decisions versus operational decisions.) This includes any decision that binds the decisions of other parts of the Project (e.g. other teams or individuals), effectively serving as an exception to the normal purviews of all teams. Some examples of policy decisions:
  • Modifying or extending existing policies, including those previously made via RFC.
  • A legal/licensing policy affecting Rust Project software or other work of the Rust Project.
  • A change to the Code of Conduct.
  • A policy affecting eligibility for membership in the Rust Project or any team thereof.
  • A change to how the moderation team moderates Council representatives or the Council as a whole. Such decisions must be made jointly with the moderation team.
  • An agreement with another project or organization that makes any ongoing commitments on behalf of the Rust Project. (One-off commitments involving teams that have agreed to those commitments are fine.)
  • Creating or substantially modifying legal structures (e.g. additional Foundations, changing relationship with the Rust Foundation, partnering with other legal entities).
  • Making policy decisions requested by one or more teams that would be within the normal purviews of those teams. (Note that teams can ask for Council input without requesting a Council decision.)
  • Deciding that a class of future decisions always belongs within the Council, rather than being delegated to any other team.
• Any decision that this document or future Council policy specifies as a public policy decision.

Conflicts of interest

A Council representative must not take part in or influence a decision in which they have a conflict of interest.

Potential sources of conflicts of interest include, but are not limited to:

• Personal: a decision about themselves
• Financial: a decision with any substantive financial impact on the representative
• Employment or equivalent: a decision involves another person at the same company, or would benefit/harm that company disproportionately more than others
• Professional or other affiliation: a decision involves an organization the representative is associated with, such as an industry/professional/standards/governmental organization
• Familial/Friendship: a decision about a person the representative cannot be expected to be impartial about, including a conflict of interest of another type through that person (such as a family member’s business)

Council representatives must promptly disclose conflicts of interest and recuse themselves from affected decisions. Council representatives must also proactively disclose likely sources of potential conflict annually to other representatives and to the moderation team.

Note that conflicts of interest can arise even if a proposal does not name a specific entity. Council representatives cannot, for instance, use their position to tailor requirements in a proposal to disproportionately benefit their employer.

A proposal favored widely across the Rust community does not automatically represent a conflict of interest for a representative merely because that representative’s employer or equivalent also favors the general area of that proposal, as long as the proposal does not favor any particular entities. For example, a proposal to improve the security of a particular Rust component is not a conflict of interest for representatives just because their employers generally care about Rust security; however, a proposal to engage specific developers or security experts, or one’s compensation being predicated on such a proposal, might still raise a conflict.

The Council may not waive a conflict of interest if one applies, even if the Council considers it minor. However, the Council may evaluate whether a conflict exists at all. Council representatives must raise potential conflicts so that the Council can make such a determination.

The Council may request specific information from a recused representative, and the recused representative may provide that information upon request.

Where possible and practical, the Council should separate decisions to reduce the scope of a conflict of interest. For instance, the Council could separate a decision to arrange access to a class of hardware (without setting specific requirements or selecting vendors) from the decision of which exact hardware to purchase and where to purchase it, if doing so made a conflict of interest only apply to the latter decision.

A representative simultaneously considering the interests of the Rust Project and the interests of any Project team is not necessarily a conflict of interest. In particular, representatives are expected to regularly take part in decisions involving their teams, as delegates from those teams.

In the unlikely event that a proposed decision produces a conflict of interest with enough representatives that the remainder cannot meet a previously established quorum requirement, and the decision must still be made, then either top-level teams must provide alternate representatives for the purposes of the specific decision, or (for public decisions only) the Council may elect to proceed with the decision while publicly documenting all conflicts of interest. (Note that proceeding with a public decision, even with conflicts documented, does not actually eliminate the conflicts or prevent them from influencing the decision; it only allows the public to judge whether the conflicts might have influenced the decision. Eliminating the conflicts entirely is always preferable.) In such a case, the Council should consider appropriate processes and policies to avoid future recurrences of a similar conflict.

Determining and changing team purviews

The Council can move an area or activity between the purviews of top-level teams either already existing or newly created (other than the moderation team). Though the purview of a given top-level team may be further sub-divided by that team, the Council only moves or adjusts top-level purviews. If a sub-divided purview is moved, the Council will work with the involved teams to coordinate the appropriate next steps. This mechanism should be used when the Council believes the existing team’s purview is too broad, such that it is not feasible to expect the team to fulfill the full purview under the current structure. However, this should not happen when a team only currently lacks resources to perform part of its duties.

The Council also must approve expansions of a top-level team’s purview, and must be notified of reductions in a top-level team’s purview. This most often happens when a team self-determines that they wish to expand or reduce their purview. This could also happen as part of top-level teams agreeing to adjust purviews between themselves. Council awareness of changes to a purview is necessary, in part, to ensure that the purview can be re-assigned elsewhere or intentionally left unassigned by the Council.

However, teams (individually or jointly) may further delegate their purviews to subteams without approval from the Council. Top-level teams remain accountable for the full purviews assigned to them, even if they delegate (in other words, teams are responsible for ensuring the delegation is successful).

The Council should favor working with teams on alternative strategies prior to shifting purviews between teams, as this is a relatively heavyweight step. It’s also worth noting that one of the use cases for this mechanism is shifting a purview previously delegated to a team that functionally no longer exists (for instance, because no one on the team has time), potentially on a relatively temporary basis until people arrive with the time and ability to re-create that team. This section intentionally does not put constraints on the Council for exactly how (or whether) this consultation should happen.

Mechanisms for oversight and accountability

The following are various mechanisms that the Council uses to keep itself and others accountable.

Ensuring the Council is accountable

The Council must publicly ensure that the wider Project and community’s expectations of the Council are consistently being met. This should be done both by adjusting the policies, procedures, and outcomes of the Council as well as education of the Project and community when their expectations are not aligned with the reality.

To achieve this, in addition to rotating representatives and adopting a “public by default” orientation, the Council must regularly (at least on a quarterly basis) provide some sort of widely available public communication on their activities as well as an evaluation of how well the Council is functioning using the list of duties, expectations, and constraints as the criteria for this evaluation.

Each year, the Council must solicit feedback on whether the Council is serving its purpose effectively from all willing and able Project members and openly discuss this feedback in a forum that allows and encourages active participation from all Project members. To do so, the Council and other Project members consult the high-level duties, expectations, and constraints listed in this document and any subsequent revisions thereof to determine if the Council is meeting its duties and obligations.

In addition, it is every representative’s individual responsibility to watch for, call out, and refuse to go along with failures to follow this document, other Council policies and procedures, or any other aspects of Council accountability. Representatives should strive to actively avoid “diffusion of responsibility”, the phenomenon in which a group of people collectively fail to do something because each individual member (consciously or subconsciously) believes that someone else will do so. The Council may also wish to designate a specific role with the responsibility of handling and monitoring procedural matters, and in particular raising procedural points of order, though others can and should still do so as well.

If any part of the above process comes to the conclusion that the Council is not meeting its obligations, then a plan for how the Council will change to better be able to meet their obligations must be presented as soon as possible. This may require an RFC changing charter or similar, a rotation of representatives, or other substantive changes. Any plan should have concrete measures for how the Council and/or Rust governance as a whole will evolve in light of the previous year’s experience.

Ensuring Council representatives are accountable

Council representatives should participate in regular feedback with each other and with their respective top-level team (the nature of which is outside the scope of this document) to reflect on how well they are fulfilling their duties as representatives. The goal of the feedback session is to help representatives better understand how they can better serve the Project. This feedback must be shared with all representatives, all members of the representative’s top-level team, and with the moderation team. This feedback should ask for both what representatives have done well and what they could have done better.

Separately, representatives should also be open to private feedback from their teams and fellow representatives at any time, and should regularly engage in self-reflection about their role and efficacy on the Council.

Artifacts from these feedback processes must never be made public to ensure a safe and open process. The Council should also reflect on and adjust the feedback process if the results do not lead to positive change.

If other members of the Council feel that a Council representative is not collaborating well with the rest of the Council, they should talk to that representative, and if necessary to that representative’s team. Council representatives should bring in moderation/mediation resources as needed to facilitate those conversations. Moderation can help resolve the issue, and/or determine if the issue is actionable and motivates some level of escalation.

While it is out of scope for this document to specify how individual teams ensure their representatives are held accountable, we encourage teams to use the above mechanisms as inspiration for their own policies and procedures.

Ensuring teams are accountable

Teams regularly coordinate and cooperate with each other, and have conversations about their needs; under normal circumstances the Council must respect the autonomy of individual teams.

However, the Council serves as a means for teams to jointly hold each other accountable, to one another and to the Project as a whole. The Council can:

• Ask a team to reconsider a decision that failed to take the considerations of other teams or the Project as a whole into consideration.
• Encourage teams to establish processes that more regularly take other teams into consideration.
• Ensure a shared understanding of teams’ purviews.
• Ensure teams are willing and able to fulfill those purviews.
• Establish new teams that split a team’s purview up into more manageable chunks.

The accountability process must not be punitive, and the process must be done with the active collaboration of the teams in question.

In extreme circumstances where teams are willfully choosing to not act in good faith with regards to the wider Project, the Council has the authority to change a team’s purview, move some subset of a team’s purview to another team, or remove a team entirely. This is done through the Council’s regular decision making process. (This does not apply to the moderation team; see the next section for accountability between the Council and moderation team.)

Footnotes

1. The term ‘authority’ here refers to the powers and responsibilities the Council has to ensure the success of the Rust Project. This document lays out the limits of these powers, so that the Council will delegate the authority it has to teams responsible for the concerns of the Project. These concerns may include - but are not limited to - product vision, day-to-day procedures, engineering decisions, mentoring, and marketing. ↩

2. Throughout this document, “teams” includes subteams, working groups, project groups, initiatives, and all other forms of official collaboration structures within the Project. “Subteams” includes all forms of collaboration structures that report up through a team. ↩

3. Subteams or individuals that fall under multiple top-level teams should not get disproportionate representation by having multiple representatives speaking for them on the Council. Whenever a “diamond” structure like this exists anywhere in the organization, the teams involved in that structure should strive to avoid ambiguity or diffusion of responsibility, and ensure people and teams know what paths they should use to raise issues and provide feedback. ↩

4. This also effectively constrains the number of Council representatives to the same range. Note that this constraint is independently important. ↩

5. The Council consists only of the representatives provided to it by top-level teams, and cannot appoint new ad hoc members to itself. However, if the Council identifies a gap in the project, it can create a new top-level team. In particular, the Council can bootstrap the creation of a team to address a problem for which the Project doesn’t currently have coordinated/organized expertise and for which the Council doesn’t know the right solution structure to charter a team solving it. In that case, the Council could bring together a team whose purview is to explore the solution-space for that problem, determine the right solution, and to return to the Council with a proposal and charter. That team would then provide a representative to the Council, who can work with the Council on aspects of that problem and solution. ↩

6. Being a Council representative is ultimately a position of service to the respective team and to the Project as a whole. While we hope that the position is fulfilling and engaging to whomever fills it, we also hope that it is not viewed as a position of status to vie for. ↩

7. In practice the infrastructure team as a whole does not have access to all credentials and internally strives to meet the principle of least privilege. ↩

8. The Council is not required to assign such roles exclusively to Council representatives; the Council may appoint any willing Project member. Such roles do not constitute membership in the Council for purposes such as decision-making. ↩

Moderation, disagreements, and conflicts

This section describes the roles of the Leadership Council and the moderation team in helping resolve disagreements and conflicts, as well as the interactions between those teams.

Disagreements and conflicts fall on a spectrum of interpersonal interaction. Disagreements are more factual and/or technical misalignments, while conflicts are more social or relational roadblocks to collaboration. Many interactions might display aspects of both disagreement and conflict. The Council can help with aspects of disagreement, while aspects of conflict are the purview of the moderation team.

This document does not specify moderation policy in general, only the portion of it necessary to specify interactions with the Council and the checks and balances between the Council and the moderation team. General moderation policy is out of scope for this document.

Much of the work of the Rust Project involves collaboration with other people, all of whom care deeply about their work. It’s normal for people to disagree, and to feel strongly about that disagreement. Disagreement can also be a powerful tool for surfacing and addressing issues, and ideally, people who disagree can collaboratively and (mostly) amicably explore those disagreements without escalating into interpersonal conflicts.

Situations where disagreements and conflicts arise may be complex. Disagreements can escalate into conflicts, and conflicts can de-escalate into disagreements. If the distinction between a disagreement and a conflict is not clear in the situation, or if participants disagree, assume the situation is a conflict.

In the event of a conflict, involved parties should reach out to the moderation team to help resolve the conflict as soon as possible. Time is a critical resource in attempting to resolve a conflict before it gets worse or causes more harm.

Disagreements among teams

Where possible, teams should attempt to resolve disagreements on their own, with assistance from the Council as needed. The Council can make judgment calls to settle disagreements, but teams need to maintain good working relationships with each other to avoid persistent disagreements or escalations into conflicts.

Potential resolution paths for disagreements between teams could include selecting a previously discussed option, devising a new option, deciding whose purview the decision falls in, or deciding that the decision is outside the purviews of both teams and leaving it to the Council to find a new home for that work.

Conflicts involving teams or Project members

Conflicts involving teams or Project members should be brought to the moderation team as soon as possible. The Council can help mitigate the impact of those conflicts on pending/urgent decisions, but the moderation team is responsible for helping with conflicts and interpersonal issues, across teams or otherwise.

Individuals or teams may also voluntarily engage in other processes to address conflicts or interpersonal issues, such as non-binding external mediation. Individuals or teams should keep the moderation team in the loop when doing so, and should seek guidance from the moderation team regarding appropriate resources or approaches for doing so. Individuals or teams must not use resources that would produce a conflict of interest.

Contingent moderators

The moderation team must at all times maintain a publicly documented list of “contingent moderators”, who must be approved by both the moderation team and the Council via internal consent decision. The moderation team and contingent moderation team should both consist of at least three members each. The contingent moderators must be:

• Not part of the current moderation team or the Leadership Council.
• Widely trusted by Rust Project members as jointly determined by the Council and moderation team; this will often mean they’re already part of the Project in some capacity.
• Qualified to do moderation work and audits as jointly determined by the Council and moderation team. More detailed criteria and guidelines will be established by moderation policy, which is out of scope for this document.
• Willing to serve as contingent moderators: willing to do audits, and willing to do interim moderation work if the moderation team dissolves or becomes unavailable, until they can appoint new full moderators. (The contingent moderators are not expected to be willing to do moderation work long-term.)
• Willing to stay familiar with moderation policy and procedure to the standards expected of a moderation team member (including any associated training). Contingent moderators should receive the same opportunities for training as the moderation team where possible.

The need for contingent moderators arises in a high-tension situation, and the Project and Council must be prepared to trust them to step into that situation. Choosing people known and trusted by the rest of the Project helps lower tensions in that situation.

Moderation is a high-burnout activity, and individual moderators or the moderation team may find itself wishing to step away from that work. Note that one or more individual moderators may always choose to step down, in which case the moderation team should identify and bring in new moderators to fill any gaps or shortfalls; if the moderation team asks a contingent moderator to become a full moderator, the team should then appoint a new contingent moderator. An individual moderator who stepped down may be selected as a contingent moderator. If the moderation team as a whole becomes simultaneously unavailable (as determined jointly by the Council and contingent moderators via internal consent decision), or chooses to step down simultaneously, the contingent moderators become the interim moderation team and must promptly appoint new contingent moderators and start seeking new full moderators.

As the contingent moderator role does not have any regular required activities outside of exceptional situations, those appointed to that role must have regular check-ins with the moderation team, to reconfirm that they’re still willing to serve in that role, and to avoid a circumstance in which the contingent moderators are abruptly needed and turn out to be unavailable.

Moderation team policies and procedures

The moderation team has a duty to have robust policies and procedures in place. The Council provides oversight and assistance to ensure that the moderation team has those policies and procedures and that they are sufficiently robust.

The Council may provide feedback to the moderation team and the moderation team is required to consider all feedback received. If the Council feels the moderation team has not followed moderation policies and procedures, the Council may require an audit by the contingent moderators. However, the Council may not overrule a moderation decision or policy.

Audits

If any Council member believes a moderation decision (or series of decisions) has not followed the moderation team’s policies and procedures, they should promptly inform the moderation team. The Council and moderation team should then engage with each other, discuss and understand these concerns, and work to address them.

One of the mechanisms this document provides for checking the moderation team’s actions in a privacy-preserving manner is an audit mechanism. In any case where any Council member believes moderation team actions have not followed documented policies or procedures, the Council member may decide to initiate the audit process. (In particular, they might do this in response to a report from a community member involved in a moderation situation.) This happens in addition to the above engagement and conversation; it is not a replacement for direct communication between the Council and the moderation team.

In an audit, the contingent moderation team works with the moderation team to establish whether the moderation team followed documented policies and procedures. This mechanism necessarily involves the contingent moderation team using their own judgment to evaluate moderation policy, specific evidence or communications, and corresponding moderation actions or proposed actions. However, this mechanism is not intended to second-guess the actions themselves; the audit mechanism focuses on establishing whether the moderation team is acting according to its established policy and procedures, as well as highlighting unintended negative consequences of the policies and procedures themselves.

The contingent moderators also reach out to the Council to find out any additional context they might need.

Moderation processes and audits both take time, and must be performed with diligence. However, the Council, contingent moderators, and moderation team should all aim to communicate their concerns and expectations to each other in a reasonably timely fashion and maintain open lines of communication.

Contingent moderators must not take part in decisions or audits for which they have a conflict of interest. Contingent moderators must not have access to private information provided to moderation before the contingent moderator was publicly listed as part of the contingent moderation team; this gives people speaking with the moderation team the opportunity to evaluate potential concerns or conflicts of interest.

The discussions with the Council and the contingent moderation team may discover that the moderation team had to make an exception in policy for a particular case, as there was an unexpected condition in policies or that there was contextual information that couldn’t be incorporated in policy. This is an expected scenario that merits additional scrutiny by the contingent moderation team on the rationale for making an exception and the process for deciding the necessity to make an exception, but is not inherently a violation of moderation team responsibilities.

As the audit process and the Council/moderation discussions proceed, the moderation team may decide to alter moderation policies and/or change the outcome of specific moderation decisions or proposed decisions. This is solely a decision for the moderation team to make.

The contingent moderation team must report the results of the audit to the moderation team and the Council for their review. This must not include any details that may reveal private information, either directly or indirectly. Together with the discussions with the moderation team, this should aim to address the concerns of the Council.

Last-resort accountability

The Leadership Council and moderation team each have substantial power within the Rust Project. This document provides many tools by which they can work out conflicts. This section outlines the last-resort mechanisms by which those teams can hold each other accountable. This section is written in the hopes that it will never be needed, and that teams will make every possible effort to resolve conflicts without reaching this point.

If the Council believes there is a systemic problem with the moderation team (whether based on an audit report from the contingent moderation team or otherwise), and the Council and moderation team cannot voluntarily come to agreement on how to address the situation, then as a last resort, the Council (by unanimous decision) may simultaneously dissolve itself and the moderation team. The top-level teams must then appoint new representatives to the Council, and the contingent moderation team becomes the new interim moderation team.

Conversely, if the moderation team believes the Council has a systemic problem, and the Council and moderation team cannot voluntarily come to agreement on how to address the situation, then as a last resort, the moderation team (by unanimous decision) may simultaneously dissolve itself and the Council. This process can only be enacted if there are at least three moderation team members. The top-level teams must then appoint new representatives to the Council, and the contingent moderation team becomes the new interim moderation team.

The moderation team’s representative is recused from the decision to dissolve the Council and moderation team to avoid conflicts of interest, though that representative must still step down as well.

The removed representatives and moderators may not serve on either the Council or the moderation team for at least one year.

By default, the new Council and interim moderation team will take responsibility for clearly communicating the transition.

This mechanism is an absolute last resort. It will almost certainly produce suboptimal outcomes, to say the least. If situations escalate to this outcome, many things have gone horribly wrong, and those cleaning up the aftermath should endeavor to prevent it from ever happening again. The indication (by either the moderation team or the Council) that the situation might escalate to this point should be considered a strong signal to come to the table and find a way to do “Something Else which is Not That” to avoid the situation.

Moderation actions involving Project members

The moderation team, in the course of doing moderation work, necessarily requires the ability to take action not just against members of the Rust community but also against members of the Rust Project. Those actions may span the ladder of escalation all the way from a conversation to removal from the Project. This puts the moderation team in a position of power and trust. This document seeks to provide appropriate accountability and cross-checks for the moderation team, as well as for the Council.

If the moderation team plans to enact externally visible sanctions against any member of the Rust Project (anything that would create a conspicuous absence, such as removal from a role, or exclusion from participation in a Project space for more than a week), then any party may request that an audit take place by reaching out to either the Council or contingent moderators, and that audit will be automatically granted.

Until June 2024, audits are automatically performed even without a request, to ensure the process is functional. After that time, the Council and moderation team will jointly review and decide whether to renew this provision.

When the moderation team sends a warning to a Project member, or sends a notification of moderation action regarding a Project member, that message will mention the option of requesting an audit.

Conflicts regarding Project members should be brought to the moderation team as soon as possible.

Conflicts involving Council representatives

Conflicts involving Council representatives, or alternates, follow the same process as conflicts involving Project members. The moderation team has the same ability to moderate representatives or alternates as any other member of the Project, including the required audit by the contingent moderators for any externally visible sanction. This remains subject to the same accountability mechanisms as for other decisions of the moderation team.

In addition to the range of moderation actions already available, the moderation team may take the following additional actions for representatives or alternates as a near-last resort, as a lesser step on the ladder of escalation than removing a member from the Project entirely. These actions are not generally specific to the Council, and apply to other Rust teams as well.

• The moderation team may decide to remove a representative from the Council. The top-level team represented by that representative should delegate a new representative to serve the remainder of the term, starting immediately.
• The moderation team may decide to prevent a Project member from becoming a Council representative.
• The moderation team and Council (excluding the affected parties) may jointly decide (as a private operational consent decision) to apply other sanctions limiting the representative’s involvement in the Council. (In this scenario, representatives are not excluded if they have a conflict of interest, as the entire Council will have to cooperate to make the sanctions effective. If the conflicts of interest thus prevent applying these partial sanctions, the moderation team always has the option of full sanctions such as removal.)

All of these also trigger a required audit. The Council must also be notified of any moderation actions involving representatives or alternates, or actions directly preventing people from becoming representatives.

Conflicts involving moderation team members

Conflicts involving a member of the moderation team will be handled by the remaining members of the moderation team (minus any with a conflict of interest), together with the contingent moderation team to provide additional oversight. Any member of the moderation or contingent moderation team should confer with the Council if there is a more systemic issue within the moderation team. The contingent moderators must audit this decision and must provide an audit report to the Council and moderation team.

Project groups

Introduction

Project groups are a kind of Rust team intended to work on a specific project with the goal bringing the project to completion. They were first defined in RFC 2856. In summary:

• Project groups are created via team consensus (such as an RFC) and have a “parent team(s)”
• The groups then drive the project to completion, e.g. by authoring follow-up RFCs and doing design work.
• Once the work has been concluded, the group is archived.
• Each project group typically has:
  • A charter outlining the group’s scope and goals.
  • Appointed shepherds and team liaisons.
  • An associated repository.
  • Dedicated streams on Discord/Zulip/etc.

Project group definition

A Project Group is a group of people working on a particular project or responsibilities at the behest of an official Rust team. Some project groups are ephemeral, meaning that they are archived once the project is complete. However, there are project groups that have continual work and maintenance.

Examples of project groups around specific feature include FFI Unwind, Inline ASM, and Safe Transmute.

The goal of a project is build a community or formalise an existing community around a particular feature or project in the organisation, and use this space to discuss and iterate on that feature.

Part of building a community is removing some of the institutional memory that develops in the design process, and centralising the information and discussion around the feature so that we can provide better visibility into why certain decisions and trade offs were made over others.

Previously a lot of the discussion and iteration for large features would happen in the initial RFC thread. This leads to a lot of discussion in the top of the thread and that often becomes completely irrelevant to the current iteration.

This process has also been unsuitable to describe features that can take multiple years to develop and will become multiple RFCs over the course of its design process. Some examples of of this are the “impl Trait” and “macros 2.0” features, where the goals has shifted a lot from the initial RFCs, and it can be hard to know their current status.

Project Group Creation

A project group should have the following;

• Leads — At least one person who acts as the leader of the group and is typically responsible for writing the initial charter, handling administrative and communication tasks, as well as delegating those responsibilities to other members in the group.
• Liaisons — A member from a official Rust team that is sponsoring the work, and acts as a point of contact between the team and the group. They may or may not be that directly involved, but they should check-in periodically and be able to represent the work in meetings with the team. They should also look out for when this might intersect with other work happening in the team that is beyond the working group itself.
  • Liaisons may also be but are not required to be one of the leads.
• Members — Individuals who regularly participate and/or contribute to the project group.
  • Membership requirements for groups are decided by the shepherd and should be stated in the charter.
  • Initial membership should try to represent people who have already been participating regularly and productively in the respective area.
  • It is not required for a project group to have a lot of members though, some project groups may only have one or two members including leads and liaisons.
• A charter that defines the scope and intent of the group.
• A GitHub repository hosted under the rust-lang organization containing the charter and instructions for how community members can monitor or participate in the group.
• Representation on the official rust-lang.org website.
• No “formal decision making power”: meaning that they are not able to accept RFCs on rust-lang/rfcs.
  • Groups are of course encouraged to create RFCs as well as advocate their concerns and desired changes to the Rust teams and community.
• Dedicated space(s) in of Rust’s officially managed discussion platforms.
  • As of the time of this writing this includes Zulip and Discord.
  • Ideally the group should use the same platform as their parent team to ease communication, though there may be cases where the team agrees to a group trying out a different platform.

Creating The Charter

Since project groups are approved by their relevant parent team, it’s up to each team decide their specific requirements. However the author recommends that a group should try to make a charter that addresses the following questions.

• What value do you see your group bringing to the organisation?
• What support do you need, and separately want, from the Rust organization?
• Why should this be a project group over a community effort?
• What are the goals of your group?
  • Both in the short term, and if relevant over a longer period.
• What are explicitly non-goals of your group?
• What do you expect the relationship to the team be?
• How do you intend to make your work accessible to people outside your group?
• Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.)
• Is your group long-running or temporary?
• If it is temporary, how long do you see it running for?
  • What is the long-term vision of your group?
• If applicable, which other groups or teams do you expect to have close contact with?
• Where do you see your group needing help?

Initial Setup

Once a group has been approved, a pull request with the initial set of members should be made to rust-lang/team. Please refer to team’s documentation for how to create a group.

It is then recommended for the project group to create a repository under the rust-lang organisation using the project group template, and making any relevant changes and personalisation.

Evaluation

Parent teams should add checking in with their project groups as part of their regular triage. The project group is also encouraged to post their progress updates and meeting minutes as blog posts on the “Inside Rust” blog.

Archival

At some point, the group’s work will conclude. Whether because the work is complete, or the members cannot finish the work, or the group feels like the project isn’t worth pursuing further. The author is calling this process “Archival”.

Announcement

A group that is considering archival should first figure out what should happen to any crates, repositories, or projects that they started. In general these projects should be migrated to other groups or individuals, or archived if there isn’t any suitable candidate for maintaining the project.

Once that has been resolved the group should write an announcement of their archival along with any relevant details about the migration and/or archival of projects.

Retrospective

While this RFC attempts to address some of the current organisational problems within the organisation, the author doesn’t believe will be a panacea to those problems or that we won’t encounter new problems in the future. As part of that, the RFC introduce having retrospectives with the groups once significant time has past or the group has finished its project.

This would involve a discussion between the members of the group, and ideally their parent team and the Governance working group. The retrospective should produce a public blog post on the Inside Rust blog, however any feedback a member has that they would want to keep private would be omitted.

The blog post should try to cover the output of the group, such as RFCs or projects, as well what the group thought worked and importantly what didn’t work. This should help us iterate on this initial RFC and help us find and address issues that come up in the process.

Both the retrospective and the archival announcement can and likely should be written as a single post. However there will be times where having a timely retrospective will not be possible, and in that case a shorter separate announcement post is appropriate.

Life-cycle of a Project Group

This is a high level overview of the complete process of a project group.

Figure 1. Project Group Lifecycle

Steps

1. Exploratory period.

   • Initial discussions of the problem area.
     • Teams are not obligated to look at or respond to any of the initial discussions. Of course, interested members are free to participate.
   • Write a short motivation for the project.
   • Find a person from the relevant team who’s willing to act as a liaison.
     • Finding a liaison is specific to each team, you should consult the team’s documentation on how to propose project groups.
     • You may not always be able to find someone who is willing to act as liaison. It’s up to each team to decide how many new efforts they’ll have the bandwidth for, which may at times be none.

2. Obtain the consensus of the team to create group.

   • Specify the liaison, and shepherd(s). (See Project Group Creation)
   • Write a short motivation, and some notes on possible solutions.
   • How consensus is reached would vary from team to team, some would require an RFC while others could decide in a meeting.

3. Create infrastructure for group.

   • GitHub repository under rust-lang for hosting work and discussions, such as for draft RFCs.
   • A Discord channel or a Zulip stream for communication.
   • Project group in rust-lang/team, as well as a team on GitHub, for handling permissions.

4. Create a post on the Inside Rust blog announcing creation of the group. Be sure to include the following information.

   • An introduction
   • The charter (either linked or inlined) [See Creating The Charter]
   • A link to your group’s GitHub repository
   • If your group is open for participants, provide information on how they can contribute.
     • If you’re also planning on running regular meetings, include when your group plans to meet along with a link to calendar event for the meeting.

5. The group works towards the goals laid out in their charter.

6. When active work has stopped a group is “archived”.

   • Archival can be started by the project group shepherds, the liaison, or the lead(s) of the parent team if needed.
   • Archival is not necessarily a permanent state, it is only a reflection on the current status of the group.
     • Similarly a groups archival doesn’t imply that work in that area has been exhausted
   • Reasons to archive (non-exhaustive):
     • Nobody in the group has time anymore or higher priority things arose.
     • There’s a blocking issue that can’t be resolved.
     • Don’t see any additional work to do in this area in the near future.
     • The work was done to a satisfactory state.
     • The group decided the idea wasn’t so good after all.

7. Create a blog post announcing the archival of the group.

   • The scope of this post will vary based on the scope of the group, but ideally it would include some of the following.
     • Overview of decisions, RFCs, and other output the group produced.
     • Thoughts on the process, how it worked (or didn’t as case may be), any difficulties encountered, and what they would want to be improved.

8. Archive infrastructure.

   • Archive GitHub repository to be read-only.
   • Archive chat channel(s) on any platforms.

Policies

These chapters contain policies covering the Rust project and its members.

Rust crate ownership policy

Introduction

This document covers the policy for crates published by the Rust project. This was initially adopted via RFC 3119.

Categories

Rust crates published by the Rust project fall into one of the following categories:

• Intentional artifacts: These are crates which are intentionally released by some team (usually libs), are actively maintained, are intended to be used by external users, and intentionally have an air of officialness. Example: libc
• Internal use: These are crates which are used by some “internal client”, like rustc, crates.io, docs.rs, etc. Their primary purpose is not to be used by external users, though the teams that maintain them (typically the teams of their internal client) may wish for the crate to have wider adoption. The line can be blurry between these and “intentional artifacts” and ultimately depends on the goals of the team. Example: conduit, measureme. There are two subcategories based on whether they are intended to ever show up as a transitive dependency:
  • Transitively intentional: These are dependencies of intentional artifact libraries, and will show up in users’ dependency trees, even if they are not intended to be directly used. The Rust Project still needs to handle security issues in these crates as if they are “intentional artifacts”.
  • Not transitively intentional: These are dependencies of shipped binaries, CI tooling, the stdlib, or are otherwise not expected to show up in users’ dependency trees. The Rust Project may need to handle security issues in these crates internally, but does not necessarily need to message the wider public about security issues in these crates. If a security issue in one of these crates affects a published binary (or crates.io, etc), that will still need to be handled as a bug in the binary or website.
• Experiment: This was an experiment by a team, intended to be picked up by users to better inform API design (or whatever), without a long-term commitment to maintainership. Example: failure
• Deprecated: This used to be an “intentional artifact” (or experiment/internal use) but isn’t anymore. Example: rustc-serialize
• Placeholder: Not a functional crate, used for holding on to the name of an official tool, etc. Example: rustup
• Expatriated: This may have been owned by the Rust Project and is still intended to be used by external users, but is no longer intended to be official. In such cases the crate is no longer owned/managed by the Rust project. Example: rand

Policy

Every crate in the organization must be owned by at least one team on crates.io. Teams should use rust-lang/foo teams for this. Non-expatriated crates may not have personal accounts as owners; if a crate needs additional owners that are not part of teams; the team should create a project group. Note that this does not forbid non-team (or project group) users from having maintainer access to the repository; it simply forbids them from publishing.

Currently it is not possible for a crate to be owned by only a team; the rust-lang-owner account (or a similar account to be decided by the infra team) can be used as a stopgap in such cases. We should try to phase this account out as much as possible, in order to make sure it is clear who is responsible for each crate. For crates being auto-published, a rust-lang/publish-bots team (or individual bot accounts) can be used to allow bot accounts to publish crates.

Each crate in the organization, and any future crates in the organization, must decide which to which category they belong in according to the above categorization. If you’re not sure what the category should be when registering a crate, or do not wish to make a decision just yet, pick “Experimental”.

Each published crate must contain a README. At a minimum, this README must mention the primary owning team. Based on their categories, crates are also required to include the following information in their READMEs and documentation roots:

Intentional artifact

“Intentional artifact” crates can choose their commitments but should be clear about what they are in their messaging. If and when a team has a charter, the crate should also be mentioned in the charter as an intentional artifact. Deprecating an intentional artifact should not be taken lightly and will require an RFC.

An example of such messaging would be text like:

This crate is maintained by The Rust [team] Team for use by the wider ecosystem. This crate is post-1.0 and follows semver compatibility for its APIs.

Security issues in these crates should be handled with the appropriate weight and careful messaging by the Security Response WG, and should be reported according to the project’s security policy.

Internal use

“Internal use” crates should contain the following text near the top of the readme/documentation:

This crate is maintained by [team], primarily for use by [rust project(s)] and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.

The “except as a transitive dependency” text should be included if the crate is a dependency of an intentional-artifact library (“transitively intentional”).

Security issues in transitively intentional libraries should be handled as if they were intentional artifacts.

Experiment

“Experiment” crates should mention they are experiments. Experiment crates may be intended to be used in a scoped sort of way; so if they are intended to be used they should be clear about what they are guaranteeing.

An example of such messaging would be text like:

This crate is maintained by [team] as a part of an experiment around [thingy]. We encourage people to try to use this crate in their projects and provide feedback through [method], but do not guarantee long term maintenance.

or, for experiments that are not intended to be used at all:

This crate is maintained by [team] and is an internal experiment. We do not guarantee stability or long term maintenance, use at your own risk.

Ideally, experimental crates that are published for feedback purposes will have a document to link to that lists out the purpose, rough duration, and processes of the experiment.

Deprecated

“Deprecated” crates should contain the following text near the top of the readme/documentation:

This crate is deprecated and not intended to be used.

Placeholder

“Placeholder” crates should contain the following text in their published readme/documentation:

This crate is a functionally empty crate that exists to reserve the crate name of [tool]. It should not be used.

In general it is better to have an empty placeholder crate published instead of reserving the crate via yanking, so that there is a readme that helps people understand why the crate is unavailable.

Expatriated

It’s unclear if any action should be taken on these beyond removing any semblance of officialness (including rust-lang/foo team owners). We currently have only one such crate (rand).

These should by and large not be considered to be “team managed” crates; this category is in this RFC for completeness to be able to talk about expatriation as an end state.

Transitions and new crates

Teams should feel free to create new crates in any of these categories; however “Intentional Artifact” crates must be accompanied with an RFC. As we move towards having team charters, this can transition to being a charter change (which may require an RFC or use its own process). Teams should notify council@rust-lang.org when they’ve created such crates so that the Leadership Council may track these crates and ensure this policy is applied.

From time to time a team’s plan for a crate may change: experiments may conclude, crates may need to be deprecated, or the team may decide to release something for wider usage.

In general, teams should notify council@rust-lang.org when such a transition is being made.

Any transition away from “Intentional Artifact” requires an RFC.

Any transition to “Intentional Artifact” should ideally be accompanied by an RFC, and an update to the team charter if there is one.

Expatriation should basically never occur anymore, but it also requires an RFC and Leadership Council approval in case it is really necessary. If a team wishes to stop working on a crate, they should deprecate it and encourage the community to fork it or build their own thing. The repository may be transferred out, however the crates.io name is kept by the Rust project and the new group of maintainers will need to pick a new crate name.

If “transitively intentional” crates are being deprecated care should be taken to ensure security issues will still be handled.

Transitions between the other types can be made at will since they explicitly and clearly state their lack of a strong stability/maintenance guarantee.

Applying this to existing crates

An audit should be performed on all existing potentially “official” crates, collecting them in a list and roughly determining what their team and category should be.

Once we have this list, we can approach teams with lists of crates and request that they verify that the categorization is accurate. In the case of some crates this might take some time as the team may need to work out what their intentions are with a particular crate.

Then, working with the teams, we make these changes to their documentation. We also make sure all crates have the appropriate rust-lang/teamname github owner, and remove personal accounts from the owners list.

For crates that are in direct use by a lot of the wider community, if we end up categorizing them as anything other than “intentional artifact”, there should be an attempt to announce this “change” to the community. While there was no formal commitment made in case of these crates, the vague sense of officialness may have made people believe there was, and we should at least try to rectify this so that people are not continually misled. Whether or not this needs to be done, and how, can be figured out by the individual teams.

A large part of this work can be parallelized; and it does not need to occur all at once.

Infrastructure

This section documents Rust’s infrastructure, and how it is maintained.

External Links

• rust-toolstate records build and test status of external tools bundled with the Rust repository.

Other Rust Installation Methods

• Which installer should you use?
• Other ways to install rustup
• Standalone installers
• Source code

Which installer should you use?

Rust runs on many platforms, and there are many ways to install Rust. If you want to install Rust in the most straightforward, recommended way, then follow the instructions on the main installation page.

That page describes installation via rustup, a tool that manages multiple Rust toolchains in a consistent way across all platforms Rust supports. Why might one not want to install using those instructions?

• Offline installation. rustup downloads components from the internet on demand. If you need to install Rust without access to the internet, rustup is not suitable.
• Preference for the system package manager. On Linux in particular, but also on macOS with Homebrew, MacPorts or pkgsrc, and Windows with Chocolatey or Scoop, developers sometimes prefer to install Rust with their platform’s package manager.
• Preference against curl | sh. On Unix, we usually install rustup by running a shell script via curl. Some have concerns about the security of this arrangement and would prefer to download and run the installer themselves.
• Validating signatures. Although rustup performs its downloads over HTTPS, the only way to verify the signatures of Rust installers today is to do so manually with the standalone installers.
• GUI installation and integration with “Add/Remove Programs” on Windows. rustup runs in the console and does not register its installation like typical Windows programs. If you prefer a more typical GUI installation on Windows there are standalone .msi installers. In the future rustup will also have a GUI installer on Windows.

Rust’s platform support is defined in three tiers, which correspond closely with the installation methods available: in general, the Rust project provides binary builds for all tier 1 and tier 2 platforms, and they are all installable via rustup. Some tier 2 platforms though have only the standard library available, not the compiler itself; that is, they are cross-compilation targets only; Rust code can run on those platforms, but they do not run the compiler itself. Such targets can be installed with the rustup target add command.

Other ways to install rustup

The way to install rustup differs by platform:

• On Unix, run curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh in your shell. This downloads and runs rustup-init.sh, which in turn downloads and runs the correct version of the rustup-init executable for your platform.
• On Windows, download and run rustup-init.exe.

rustup-init can be configured interactively, and all options can additionally be controlled by command-line arguments, which can be passed through the shell script. Pass --help to rustup-init as follows to display the arguments rustup-init accepts:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --help

If you prefer not to use the shell script, you may directly download rustup-init for the platform of your choice:

• aarch64-apple-darwin
• aarch64-linux-android
• aarch64-pc-windows-msvc
• aarch64-unknown-linux-gnu
• aarch64-unknown-linux-musl
• arm-linux-androideabi
• arm-unknown-linux-gnueabi
• arm-unknown-linux-gnueabihf
• armv7-linux-androideabi
• armv7-unknown-linux-gnueabihf
• i686-apple-darwin
• i686-linux-android
• i686-pc-windows-gnu
• i686-pc-windows-msvc
• i686-unknown-linux-gnu
• loongarch64-unknown-linux-gnu
• loongarch64-unknown-linux-musl
• mips-unknown-linux-gnu
• mips64-unknown-linux-gnuabi64
• mips64el-unknown-linux-gnuabi64
• mipsel-unknown-linux-gnu
• powerpc-unknown-linux-gnu
• powerpc64-unknown-linux-gnu
• powerpc64le-unknown-linux-gnu
• powerpc64le-unknown-linux-musl
• s390x-unknown-linux-gnu
• x86_64-apple-darwin
• x86_64-linux-android
• x86_64-pc-windows-gnu
• x86_64-pc-windows-msvc
• x86_64-unknown-freebsd
• x86_64-unknown-illumos
• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• x86_64-unknown-netbsd

Standalone installers

The official Rust standalone installers contain a single release of Rust, and are suitable for offline installation. They come in three forms: tarballs (extension .tar.xz), that work in any Unix-like environment, Windows installers (.msi), and Mac installers (.pkg). These installers come with rustc, cargo, rustdoc, the standard library, and the standard documentation, but do not provide access to additional cross-targets like rustup does.

The most common reasons to use these are:

• Offline installation
• Preferring a more platform-integrated, graphical installer on Windows

Each of these binaries is signed with the Rust signing key, which is available on keybase.io, by the Rust build infrastructure, with GPG. In the tables below, the .asc files are the signatures.

Past releases can be found in the archive.

Source code

If you want to build the Rust toolchain from source code, you can use the following links to download source code tarballs.

If you want to make sure that the published source tarball matches what is in the rust git repository, you can use the following script as a template:

#!/bin/bash

set -e

# You can use either a commit SHA or a stable release version (e.g. 1.XY.Z)
TAG=a8cfc83801301c2b4f0fd030192e268eeb15d473
# TAG=1.77.1

# Clone Rust toolchain repository from GitHub
git clone https://github.com/rust-lang/rust
cd rust
git reset --hard ${TAG}

cat >config.toml << EOF
[rust]
# Use for a commit SHA
channel = "nightly"

# Use for a stable release
# channel = "stable"

[dist]
compression-formats = ["xz"]
compression-profile = "fast"
EOF

# Build the source tarball from git into build/dist/
./x dist rustc-src

# Download source tarball for a commit SHA
wget https://ci-artifacts.rust-lang.org/rustc-builds/${TAG}/rustc-nightly-src.tar.xz

# Download a source tarball for a stable release
# wget https://static.rust-lang.org/dist/rustc-${TAG}-src.tar.xz

# Decompress the tarballs and check if they're the same
xz --decompress rustc-*-src.tar.xz
xz --decompress build/dist/rustc-*-src.tar.xz
diff rustc-*-src.tar build/dist/rustc-*-src.tar

Archive of Rust Stable Standalone Installers

Note: The Rust project only supports the latest stable release with security patches. Generally speaking these archives should not be used without some extra mechanisms to provide for patching.

The official Rust standalone installers contain a single release of Rust, and are suitable for offline installation. They come in three forms: tarballs (extension .tar.xz), that work in any Unix-like environment, Windows installers (.msi), and Mac installers (.pkg). These installers come with rustc, cargo, rustdoc, the standard library, and the standard documentation, but do not provide access to additional cross-targets like rustup does.

The most common reasons to use these are:

• Offline installation
• Preferring a more platform-integrated, graphical installer on Windows

Each of these binaries is signed with the Rust signing key, which is available on keybase.io, by the Rust build infrastructure, with GPG. In the tables below, the .asc files are the signatures.

Stable (1.86.0)

Stable (1.85.1)

Stable (1.85.0)

Stable (1.84.1)

Stable (1.84.0)

Stable (1.83.0)

Stable (1.82.0)

Stable (1.81.0)

Stable (1.80.1)

Stable (1.80.0)

Stable (1.79.0)