Contribution procedures

Bug reports

While bugs are unfortunate, they’re a reality in software.We can’t fix what we don’t know about, so please report liberally.If you’re not sure if something is a bug, feel free to open an issue anyway.

If you believe reporting your bug publicly represents a security risk to Rust users,please follow ourinstructions for reporting security vulnerabilities.

If you’re using the nightly channel, please check if the bug exists in thelatest toolchain before filing your bug.It might be fixed already.

If you have the chance, before reporting a bug, pleasesearch existing issues,as it’s possible that someone else has already reported your error.This doesn’t always work, and sometimes it’s hard to know what to search for, so consider thisextra credit.We won’t mind if you accidentally file a duplicate report.

Similarly, to help others who encountered the bug find your issue, considerfiling an issue with a descriptive title, which contains information that might be unique to it.This can be the language or compiler feature used, theconditions that trigger the bug, or part of the error message if there is any.An example could be:“impossible case reached” on lifetime inference for implTrait in return position.

Opening an issue is as easy as followingthis link and filling out the fieldsin the appropriate provided template.

Bug fixes or “normal” code changes

For most PRs, no special procedures are needed.You can justopen a PR, and it will be reviewed, approved, and merged.This includes most bug fixes, refactorings, and other user-invisible changes.The next few sections talk about exceptions to this rule.

Also, note that it is perfectly acceptable to open WIP PRs or GitHubDraft PRs.Some people prefer to do this so they can get feedback along theway or share their code with a collaborator.Others do this so they can utilizethe CI to build and test their PR (e.g. when developing on a slow machine).

New features

Rust has strong backwards-compatibility guarantees.Thus, new features can’t just be implemented directly in stable Rust.Instead, we have 3 release channels: stable, beta, and nightly.SeeThe Rust Book for more details on Rust’s train release model.

• Stable: this is the latest stable release for general usage.
• Beta: this is the next release (will be stable within 6 weeks).
• Nightly: follows themain branch of the repo.This is the only channel where unstable features are intended to be used,which happens via opt-in feature gates.

Seethis chapter on implementing new features for moreinformation.

Breaking changes

Breaking changes have adedicated section in the dev-guide.

Major changes

The compiler team has a special process for large changes, whether or not they cause breakage.This process is called a Major Change Proposal (MCP).MCP is a relatively lightweight mechanism for getting feedback on large changes to thecompiler (as opposed to a full RFC or a design meeting with the team).

Example of things that might require MCPs include major refactorings, changesto important types, or important changes to how the compiler does something, orsmaller user-facing changes.

When in doubt, askon Zulip.It would be a shame to put a lot of workinto a PR that ends up not getting merged!See this document for more info on MCPs.

Performance

Compiler performance is important.We have put a lot of effort over the last few years intogradually improving it.

If you suspect that your change may cause a performance regression (orimprovement), you can request a “perf run” (and your reviewer may also request onebefore approving).This is yet another bot that will compile a collection ofbenchmarks on a compiler with your changes.The numbers are reportedhere, and you can see a comparison of your changes against the latestmain.

For an introduction to the performance of Rust code in generalwhich would also be useful in rustc development, seeThe Rust Performance Book.

Pull requests

Pull requests (or PRs for short) are the primary mechanism we use to change Rust.GitHub itself has somegreat documentation on using the Pull Request feature.We use the“fork and pull” model,where contributors push changes to their personal fork and create pull requests tobring those changes into the source repository.We havea chapter on how to use Git when contributing to Rust.

Advice for potentially large, complex, cross-cutting and/or very domain-specific changes

The compiler reviewers on rotation usually each have areas of the compiler that they know well,but also have areas that they are not very familiar with. If your PR contains changes that arelarge, complex, cross-cutting and/or highly domain-specific, it becomes very difficult to find asuitable reviewer who is comfortable in reviewing all of the changes in such a PR. This is alsotrue if the changes are not only compiler-specific but also contains changes which fall under thepurview of reviewers from other teams, like the standard library team.There’s a botwhich notifies the relevant teams and pings people who have setup specific alerts based on thefiles modified.

Before making such changes, you are strongly encouraged todiscuss your proposed changes withthe compiler team beforehand (and with other teams that the changes would require approvalfrom), and work with the compiler team to see if we can help youbreak down a large potentiallyunreviewable PR into a series of smaller more individually reviewable PRs.

You can communicate with the compiler team by creating a#t-compiler thread on Zulipto discuss your proposed changes.

Communicating with the compiler team beforehand helps in several ways:

1. It increases the likelihood of your PRs being reviewed in a timely manner.
   • We can help you identify suitable reviewersbefore you open actual PRs, or help findadvisors and liaisons to help you navigate the change procedures, or help with runningtry-jobs, perf runs and crater runs as suitable.
2. It helps the compiler team track your changes.
3. The compiler team can perform vibe checks on your changes early and often, to see if thedirection of the changes align with what the compiler team prefers to see.
4. Helps to avoid situations where you may have invested significant time and effort into largechanges that the compiler team might not be willing to accept, or finding out very late that thechanges are in a direction that the compiler team disagrees with.

Keeping your branch up-to-date

The CI in rust-lang/rust applies your patches directly against currentmain,not against the commit your branch is based on.This can lead to unexpected failuresif your branch is outdated, even when there are no explicit merge conflicts.

Update your branch only when needed: when you have merge conflicts, upstream CI is broken and blocking your green PR, or a maintainer requests it.Avoid updating an already-green PR under review unless necessary.During review, make incremental commits to address feedback.Prefer to squash or rebase only at the end, or when a reviewer requests it.

When updating, usegit push --force-with-lease and leave a brief comment explaining what changed.Some repos prefer merging fromupstream/main instead of rebasing;follow the project’s conventions.Seekeeping things up to date for detailed instructions.

After rebasing, it’s recommended torun the relevant tests locally to catch any issues before CI runs.

r?

All pull requests are reviewed by another person.We have a bot,@rustbot, that will automatically assign a random personto review your request based on which files you changed.

If you want to request that a specific person reviews your pull request, youcan add anr? to the pull request description or in a comment.For example, if you want to ask a review by @awesome-reviewer,add the following to the end of the pull request description:

r? @awesome-reviewer

@rustbot will then assign the PR to that reviewer instead of a random person.This is entirely optional.

You can also assign a random reviewer from a specific team by writingr? rust-lang/groupname.As an example, if you were making a diagnostics change,you could get a reviewer from the diagnostics team by adding:

r? rust-lang/diagnostics

For a full list of possiblegroupnames,check theadhoc_groups section at thetriagebot.toml config file,or the list of teams in therust-lang teams database.

Waiting for reviews

NOTE

Pull request reviewers are often working at capacity,and many of them are contributing on a volunteer basis.In order to minimize review delays,pull request authors and assigned reviewers should ensure that the review label(S-waiting-on-review andS-waiting-on-author) stays updated,invoking these commands when appropriate:

• @rustbot author:the review is finished,and PR author should check the comments and take action accordingly.

• @rustbot review:the author is ready for a review,and this PR will be queued again in the reviewer’s queue.

Please note that the reviewers are humans, who for the most part work onrustc in their free time.This means that they can take some time to respond and review your PR.It also means that reviewers can miss some PRs that are assigned to them.

To try to move PRs forward, the Triage WG regularly goes through all PRs thatare waiting for review and haven’t been discussed for at least 2 weeks.If you don’t get a review within 2 weeks, feel free to ask the Triage WG onZulip (#t-release/triage).They have knowledge of when to ping, who might be on vacation, etc.

The reviewer may request some changes using the GitHub code review interface.They may also request special procedures for some PRs.SeeCrater andBreaking Changes chapters for some examples of such procedures.

CI

In addition to being reviewed by a human, pull requests are automatically tested,thanks to continuous integration (CI).Basically, every time you open and updatea pull request, CI builds the compiler and tests it against thecompiler test suite, and also performs other tests such as checking thatyour pull request is in compliance with Rust’s style guidelines.

Running continuous integration tests allows PR authors to catch mistakes earlywithout going through a first review cycle, and also helps reviewers stay awareof the status of a particular pull request.

Rust has plenty of CI capacity, and you should never have to worry about wastingcomputational resources each time you push a change.It is also perfectly fine(and even encouraged!) to use the CI to test your changes if it can help your productivity.In particular, we don’t recommend running the full./x test suite locally,since it takes a very long time to execute.

r+

After someone has reviewed your pull request, they will leave an annotationon the pull request with anr+.It will look something like this:

@bors r+

This tells@bors, our lovable integration bot, that your pull request has been approved.The PR then enters themerge queue, where@borswill runall the tests onevery platform we support.If it all works out,@bors will merge your code intomain and close the pull request.

Depending on the scale of the change, you may see a slightly different form ofr+:

@bors r+ rollup

The additionalrollup tells@bors that this change should always be “rolled up”.Changes that are rolled up are tested and merged alongside other PRs, to speed the process up.Typically, only small changes that are expected not to conflictwith one another are marked as “always roll up”.

Be patient;this can take a while and the queue can sometimes be long.Also, note that PRs are never merged by hand.

Opening a PR

You are now ready to file a pull request (PR)?Great!Here are a few points you should be aware of.

All pull requests should be filed against themain branch,unless you know for sure that you should target a different branch.

Run some style checks before you submit the PR:

./x test tidy --bless

We recommend to make this check before every pull request (and every new commit in a pull request);you can addgit hooks before every push to make sure you never forget to make this check.The CI will also run tidy and will fail if tidy fails.

Rust follows ano merge-commit policy,meaning that when you encounter merge conflicts,you are expected to always rebase instead of merging.For example,always use rebase when bringing the latest changes from themain branch to your feature branch.If your PR contains merge commits, it will get marked ashas-merge-commits.Once you have removed the merge commits, e.g., through an interactive rebase, youshould remove the label again:

@rustbot label -has-merge-commits

Seethis chapter for more details.

If you encounter merge conflicts or when a reviewer asks you to perform somechanges, your PR will get marked asS-waiting-on-author.When you resolve them, you should use@rustbot to mark it asS-waiting-on-review:

@rustbot ready

GitHub allowsclosing issues using keywords.This feature should be used to keep the issue tracker tidy.However, it is generally preferredto put the “closes #123” text in the PR description rather than the commit message;particularly during rebasing, citing the issue number in the commit can “spam”the issue in question.

However, if your PR fixes a stable-to-beta or stable-to-stable regression and hasbeen accepted for a beta and/or stable backport (i.e., it is markedbeta-acceptedand/orstable-accepted), please donot use any such keywords since we don’twant the corresponding issue to get auto-closed once the fix lands onmain.Please update the PR description while still mentioning the issue somewhere.For example, you could writeFixes (after beta backport) #NNN..

As for further actions, please keep a sharp look-out for a PR whose title begins with[beta] or[stable] and which backports the PR in question.When that one gets merged, the relevant issue can be closed.The closing comment should mention all PRs that were involved.If you don’t have the permissions to close the issue, pleaseleave a comment on the original PR asking the reviewer to close it for you.

Reverting a PR

When a PR leads to miscompile, significant performance regressions, or other critical issues, we maywant to revert that PR with a regression test case.You can also check out therevert policy onForge docs (which is mainly targeted for reviewers, but contains useful info for PR authors too).

If the PR contains huge changes, it can be challenging to revert, making it harder to reviewincremental fixes in subsequent updates.Or if certain code in that PR is heavily depended upon bysubsequent PRs, reverting it can become difficult.

In such cases, we can identify the problematic code and disable it for some input, as shown in#128271.

For MIR optimizations, we can also use the-Zunsound-mir-opt option to gate the mir-opt, as shownin#132356.

External dependencies

This section has moved to“Using External Repositories”.

Writing documentation

Documentation improvements are very welcome.The source ofdoc.rust-lang.orgis located insrc/doc in the tree, and standard API documentation is generatedfrom the source code itself (e.g.library/std/src/lib.rs). Documentation pull requestsfunction in the same way as other pull requests.

To find documentation-related issues, use theA-docs label.

You can find documentation style guidelines inRFC 1574.

To build the standard library documentation, usex doc --stage 1 library --open.To build the documentation for a book (e.g. the unstable book), usex doc src/doc/unstable-book.Results should appear inbuild/host/doc, as well as automatically open in your default browser.SeeBuilding Documentation for moreinformation.

You can also userustdoc directly to check small fixes.For example,rustdoc src/doc/reference.md will render reference todoc/reference.html.The CSS might be messed up, but you can verify that the HTML is right.

Please notice that we don’t accept typography/spellcheck fixes tointernal documentationas it’s usually not worth the churn or the review time.Examples of internal documentation is code comments and rustc api docs.However, feel free to fix those if accompanied by other improvements in the same PR.

Contributing to rustc-dev-guide

Contributions to therustc-dev-guide are always welcome, and can be made directly atthe rust-lang/rustc-dev-guide repo.The issue tracker in that repo is also a great way to find things that need doing.There are issues for beginners and advanced compiler devs alike!

Just a few things to keep in mind:

• Please try to avoid overly long lines and use semantic line breaks (where you break the line after each sentence).There is no strict limit on line lengths;let the sentence or part of the sentence flow to its proper end on the same line.

  You can use a tool in ci/sembr to help with this.Its help output can be seen with this command:

  cargo run --manifest-path ci/sembr/Cargo.toml -- --help

• When contributing text to the guide, please contextualize the information with some time periodand/or a reason so that the reader knows how much to trust the information.Aim to provide a reasonable amount of context, possibly including but not limited to:

  • A reason for why the text may be out of date other than “change”,as change is a constant across the project.

  • The date the comment was added, e.g. instead of writing“Currently, …”or“As of now, …”, consider adding the date, in one of the following formats:

    • Jan 2021
    • January 2021
    • jan 2021
    • january 2021

    There is a CI action (in.github/workflows/date-check.yml)that generates a monthly report showing those that are over 6 months old(example).

    For the action to pick the date, add a special annotation before specifying the date:

    <!-- date-check --> Nov 2025

    Example:

    As of <!-- date-check --> Nov 2025, the foo did the bar.

    For cases where the date should not be part of the visible rendered output,use the following instead:

    <!-- date-check: Nov 2025 -->

  • A link to a relevant WG, tracking issue,rustc rustdoc page, or similar, that may providefurther explanation for the change process or a way to verify that the information is notoutdated.

• If a text grows rather long (more than a few page scrolls) or complicated (more than foursubsections), it might benefit from having a Table of Contents at the beginning,which you can auto-generate by including the<!-- toc --> marker at the top.

⚠️ Note: Where to contributerustc-dev-guide changes

For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so,seethe rustc-dev-guide team documentation.

Issue triage

Please seehttps://forge.rust-lang.org/release/issue-triaging.html.

rfcbot labels

rfcbot uses its own labels for tracking the process of coordinatingasynchronous decisions, such as approving or rejecting a change.This is used forRFCs, issues, and pull requests.

Helpful links and information

This section has moved to the“About this guide” chapter.