mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
rustc-dev-guide/contributing.html

604 lines
38 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Contribution procedures - Rust Compiler Development Guide</title>
<!-- Custom HTML head -->
<meta name="description" content="A guide to developing the Rust compiler (rustc)">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Rust Compiler Development Guide</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/contributing.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="contribution-procedures"><a class="header" href="#contribution-procedures">Contribution procedures</a></h1>
<ul>
<li><a href="#bug-reports">Bug reports</a></li>
<li><a href="#bug-fixes-or-normal-code-changes">Bug fixes or "normal" code changes</a></li>
<li><a href="#new-features">New features</a>
<ul>
<li><a href="#breaking-changes">Breaking changes</a></li>
<li><a href="#major-changes">Major changes</a></li>
<li><a href="#performance">Performance</a></li>
</ul>
</li>
<li><a href="#pull-requests">Pull requests</a>
<ul>
<li><a href="#keeping-your-branch-up-to-date">Keeping your branch up-to-date</a></li>
<li><a href="#r">r?</a></li>
<li><a href="#waiting-for-reviews">Waiting for reviews</a></li>
<li><a href="#ci">CI</a></li>
<li><a href="#r-1">r+</a></li>
<li><a href="#opening-a-pr">Opening a PR</a></li>
<li><a href="#reverting-a-pr">Reverting a PR</a></li>
</ul>
</li>
<li><a href="#external-dependencies">External dependencies</a></li>
<li><a href="#writing-documentation">Writing documentation</a>
<ul>
<li><a href="#contributing-to-rustc-dev-guide">Contributing to rustc-dev-guide</a></li>
</ul>
</li>
<li><a href="#issue-triage">Issue triage</a>
<ul>
<li><a href="#rfcbot-labels">Rfcbot labels</a></li>
</ul>
</li>
<li><a href="#helpful-links-and-information">Helpful links and information</a></li>
</ul>
<h2 id="bug-reports"><a class="header" href="#bug-reports">Bug reports</a></h2>
<p>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 or not, feel free to file a bug anyway.</p>
<p><strong>If you believe reporting your bug publicly represents a security risk to Rust users,
please follow our <a href="https://www.rust-lang.org/policies/security">instructions for reporting security vulnerabilities</a></strong>.</p>
<p>If you're using the nightly channel, please check if the bug exists in the
latest toolchain before filing your bug. It might be fixed already.</p>
<p>If you have the chance, before reporting a bug, please <a href="https://github.com/rust-lang/rust/issues?q=is%3Aissue">search existing issues</a>,
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 this
extra credit. We won't mind if you accidentally file a duplicate report.</p>
<p>Similarly, to help others who encountered the bug find your issue, consider
filing an issue with a descriptive title, which contains information that might
be unique to it. This can be the language or compiler feature used, the
conditions that trigger the bug, or part of the error message if there is any.
An example could be: <strong>"impossible case reached" on lifetime inference for impl
Trait in return position</strong>.</p>
<p>Opening an issue is as easy as following <a href="https://github.com/rust-lang/rust/issues/new/choose">this
link</a> and filling out the fields
in the appropriate provided template.</p>
<h2 id="bug-fixes-or-normal-code-changes"><a class="header" href="#bug-fixes-or-normal-code-changes">Bug fixes or "normal" code changes</a></h2>
<p>For most PRs, no special procedures are needed. You can just <a href="#pull-requests">open a PR</a>, 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.</p>
<p>Also, note that it is perfectly acceptable to open WIP PRs or GitHub <a href="https://github.blog/2019-02-14-introducing-draft-pull-requests/">Draft PRs</a>.
Some people prefer to do this so they can get feedback along the
way or share their code with a collaborator. Others do this so they can utilize
the CI to build and test their PR (e.g. when developing on a slow machine).</p>
<h2 id="new-features"><a class="header" href="#new-features">New features</a></h2>
<p>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.</p>
<ul>
<li><strong>Stable</strong>: this is the latest stable release for general usage.</li>
<li><strong>Beta</strong>: this is the next release (will be stable within 6 weeks).</li>
<li><strong>Nightly</strong>: follows the <code>master</code> branch of the repo. This is the only
channel where unstable, incomplete, or experimental features are usable with
feature gates.</li>
</ul>
<p>See <a href="./implementing_new_features.html">this chapter on implementing new features</a> for more
information.</p>
<h3 id="breaking-changes"><a class="header" href="#breaking-changes">Breaking changes</a></h3>
<p>Breaking changes have a <a href="bug-fix-procedure.html">dedicated section</a> in the dev-guide.</p>
<h3 id="major-changes"><a class="header" href="#major-changes">Major changes</a></h3>
<p>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 the
compiler (as opposed to a full RFC or a design meeting with the team).</p>
<p>Example of things that might require MCPs include major refactorings, changes
to important types, or important changes to how the compiler does something, or
smaller user-facing changes.</p>
<p><strong>When in doubt, ask on <a href="https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler">zulip</a>. It would be a shame to put a lot of work
into a PR that ends up not getting merged!</strong> <a href="https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#how-do-i-submit-an-mcp">See this document</a> for
more info on MCPs.</p>
<h3 id="performance"><a class="header" href="#performance">Performance</a></h3>
<p>Compiler performance is important. We have put a lot of effort over the last
few years into <a href="https://perf.rust-lang.org/dashboard.html">gradually improving it</a>.</p>
<p>If you suspect that your change may cause a performance regression (or
improvement), you can request a "perf run" (and your reviewer may also request one
before approving). This is yet another bot that will compile a collection of
benchmarks on a compiler with your changes. The numbers are reported
<a href="https://perf.rust-lang.org">here</a>, and you can see a comparison of your changes against the latest
master.</p>
<blockquote>
<p>For an introduction to the performance of Rust code in general
which would also be useful in rustc development, see <a href="https://nnethercote.github.io/perf-book/">The Rust Performance Book</a>.</p>
</blockquote>
<h2 id="pull-requests"><a class="header" href="#pull-requests">Pull requests</a></h2>
<p>Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
GitHub itself has some <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests">great documentation</a> on using the
Pull Request feature. We use the "fork and pull" model <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model">described here</a>,
where contributors push changes to their personal fork and create pull requests to
bring those changes into the source repository. We have more info about how to use git
when contributing to Rust under <a href="./git.html">the git section</a>.</p>
<blockquote>
<p><strong>Advice for potentially large, complex, cross-cutting and/or very domain-specific changes</strong></p>
<p>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 are
large, complex, cross-cutting and/or highly domain-specific, it becomes very difficult to find a
suitable reviewer who is comfortable in reviewing all of the changes in such a PR. This is also
true if the changes are not only compiler-specific but also contains changes which fall under the
purview of reviewers from other teams, like the standard library team. <a href="https://github.com/rust-lang/rust/blob/master/triagebot.toml">There's a bot</a>
which notifies the relevant teams and pings people who have setup specific alerts based on the
files modified.</p>
<p>Before making such changes, you are strongly encouraged to <strong>discuss your proposed changes with
the compiler team beforehand</strong> (and with other teams that the changes would require approval
from), and work with the compiler team to see if we can help you <strong>break down a large potentially
unreviewable PR into a series of smaller more individually reviewable PRs</strong>.</p>
<p>You can communicate with the compiler team by creating a <a href="https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler">#t-compiler thread on zulip</a>
to discuss your proposed changes.</p>
<p>Communicating with the compiler team beforehand helps in several ways:</p>
<ol>
<li>It increases the likelihood of your PRs being reviewed in a timely manner.
<ul>
<li>We can help you identify suitable reviewers <em>before</em> you open actual PRs, or help find
advisors and liaisons to help you navigate the change procedures, or help with running
try-jobs, perf runs and crater runs as suitable.</li>
</ul>
</li>
<li>It helps the compiler team track your changes.</li>
<li>The compiler team can perform vibe checks on your changes early and often, to see if the
direction of the changes align with what the compiler team prefers to see.</li>
<li>Helps to avoid situations where you may have invested significant time and effort into large
changes that the compiler team might not be willing to accept, or finding out very late that the
changes are in a direction that the compiler team disagrees with.</li>
</ol>
</blockquote>
<h3 id="keeping-your-branch-up-to-date"><a class="header" href="#keeping-your-branch-up-to-date">Keeping your branch up-to-date</a></h3>
<p>The CI in rust-lang/rust applies your patches directly against the current master,
not against the commit your branch is based on. This can lead to unexpected failures
if your branch is outdated, even when there are no explicit merge conflicts.</p>
<p>Before submitting or updating a PR, make sure to update your branch
as mentioned <a href="git.html#keeping-things-up-to-date">here</a> if it's significantly
behind the master branch (e.g., more than 100 commits behind).
This fetches the latest master branch and rebases your changes on top of it,
ensuring your PR is tested against the latest code.</p>
<p>After rebasing, it's recommended to <a href="tests/intro.html">run the relevant tests locally</a> to catch any issues before CI runs.</p>
<h3 id="r"><a class="header" href="#r">r?</a></h3>
<p>All pull requests are reviewed by another person. We have a bot,
<a href="https://github.com/rustbot">@rustbot</a>, that will automatically assign a random person
to review your request based on which files you changed.</p>
<p>If you want to request that a specific person reviews your pull request, you
can add an <code>r?</code> to the pull request description or in a comment. For example,
if you want to ask a review to @awesome-reviewer, add</p>
<pre><code>r? @awesome-reviewer
</code></pre>
<p>to the end of the pull request description, and <a href="https://github.com/rustbot">@rustbot</a> will assign
them instead of a random person. This is entirely optional.</p>
<p>You can also assign a random reviewer from a specific team by writing <code>r? rust-lang/groupname</code>.
As an example,
if you were making a diagnostics change,
then you could get a reviewer from the diagnostics team by adding:</p>
<pre><code>r? rust-lang/diagnostics
</code></pre>
<p>For a full list of possible <code>groupname</code>s,
check the <code>adhoc_groups</code> section at the <a href="https://github.com/rust-lang/rust/blob/HEAD/triagebot.toml">triagebot.toml config file</a>,
or the list of teams in the <a href="https://github.com/rust-lang/team/tree/HEAD/teams">rust-lang teams database</a>.</p>
<h3 id="waiting-for-reviews"><a class="header" href="#waiting-for-reviews">Waiting for reviews</a></h3>
<blockquote>
<p>NOTE</p>
<p>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
(<code>S-waiting-on-review</code> and <code>S-waiting-on-author</code>) stays updated,
invoking these commands when appropriate:</p>
<ul>
<li>
<p><code>@rustbot author</code>:
the review is finished,
and PR author should check the comments and take action accordingly.</p>
</li>
<li>
<p><code>@rustbot review</code>:
the author is ready for a review,
and this PR will be queued again in the reviewer's queue.</p>
</li>
</ul>
</blockquote>
<p>Please note that the reviewers are humans, who for the most part work on <code>rustc</code>
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.</p>
<p>To try to move PRs forward, the Triage WG regularly goes through all PRs that
are 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 on
Zulip (<a href="https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage">#t-release/triage</a>). They have knowledge of when to ping, who might be
on vacation, etc.</p>
<p>The reviewer may request some changes using the GitHub code review interface.
They may also request special procedures for some PRs.
See <a href="tests/crater.html">Crater</a> and <a href="bug-fix-procedure.html">Breaking Changes</a> chapters for some examples of such procedures.</p>
<h3 id="ci"><a class="header" href="#ci">CI</a></h3>
<p>In addition to being reviewed by a human, pull requests are automatically tested,
thanks to continuous integration (CI). Basically, every time you open and update
a pull request, CI builds the compiler and tests it against the
<a href="tests/intro.html">compiler test suite</a>, and also performs other tests such as checking that
your pull request is in compliance with Rust's style guidelines.</p>
<p>Running continuous integration tests allows PR authors to catch mistakes early
without going through a first review cycle, and also helps reviewers stay aware
of the status of a particular pull request.</p>
<p>Rust has plenty of CI capacity, and you should never have to worry about wasting
computational 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 <code>./x test</code> suite locally,
since it takes a very long time to execute.</p>
<h3 id="r-1"><a class="header" href="#r-1">r+</a></h3>
<p>After someone has reviewed your pull request, they will leave an annotation
on the pull request with an <code>r+</code>. It will look something like this:</p>
<pre><code>@bors r+
</code></pre>
<p>This tells <a href="https://github.com/bors">@bors</a>, our lovable integration bot, that your pull request has
been approved. The PR then enters the <a href="https://bors.rust-lang.org/queue/rust">merge queue</a>, where <a href="https://github.com/bors">@bors</a>
will run <em>all</em> the tests on <em>every</em> platform we support. If it all works out,
<a href="https://github.com/bors">@bors</a> will merge your code into <code>master</code> and close the pull request.</p>
<p>Depending on the scale of the change, you may see a slightly different form of <code>r+</code>:</p>
<pre><code>@bors r+ rollup
</code></pre>
<p>The additional <code>rollup</code> tells <a href="https://github.com/bors">@bors</a> 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 conflict
with one another are marked as "always roll up".</p>
<p>Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.</p>
<h3 id="opening-a-pr"><a class="header" href="#opening-a-pr">Opening a PR</a></h3>
<p>You are now ready to file a pull request? Great! Here are a few points you
should be aware of.</p>
<p>All pull requests should be filed against the <code>master</code> branch,
unless you know for sure that you should target a different branch.</p>
<p>Make sure your pull request is in compliance with Rust's style guidelines by running</p>
<pre><code>$ ./x test tidy --bless
</code></pre>
<p>We recommend to make this check before every pull request (and every new commit
in a pull request); you can add <a href="https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks">git hooks</a>
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.</p>
<p>Rust follows a <em>no merge-commit policy</em>, meaning, when you encounter merge
conflicts you are expected to always rebase instead of merging. E.g. always use
rebase when bringing the latest changes from the master branch to your feature
branch. If your PR contains merge commits, it will get marked as <code>has-merge-commits</code>.
Once you have removed the merge commits, e.g., through an interactive rebase, you
should remove the label again:</p>
<pre><code>@rustbot label -has-merge-commits
</code></pre>
<p>See <a href="./rustbot.html#issue-relabeling">this chapter</a> for more details.</p>
<p>If you encounter merge conflicts or when a reviewer asks you to perform some
changes, your PR will get marked as <code>S-waiting-on-author</code>. When you resolve
them, you should use <code>@rustbot</code> to mark it as <code>S-waiting-on-review</code>:</p>
<pre><code>@rustbot ready
</code></pre>
<p>GitHub allows <a href="https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue">closing issues using keywords</a>. This feature
should be used to keep the issue tracker tidy. However, it is generally preferred
to put the "closes #123" text in the PR description rather than the issue commit;
particularly during rebasing, citing the issue number in the commit can "spam"
the issue in question.</p>
<p>However, if your PR fixes a stable-to-beta or stable-to-stable regression and has
been accepted for a beta and/or stable backport (i.e., it is marked <code>beta-accepted</code>
and/or <code>stable-accepted</code>), please do <em>not</em> use any such keywords since we don't
want the corresponding issue to get auto-closed once the fix lands on master.
Please update the PR description while still mentioning the issue somewhere.
For example, you could write <code>Fixes (after beta backport) #NNN.</code>.</p>
<p>As for further actions, please keep a sharp look-out for a PR whose title begins with
<code>[beta]</code> or <code>[stable]</code> 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, please
leave a comment on the original PR asking the reviewer to close it for you.</p>
<h3 id="reverting-a-pr"><a class="header" href="#reverting-a-pr">Reverting a PR</a></h3>
<p>When a PR leads to miscompile, significant performance regressions, or other critical issues, we may
want to revert that PR with a regression test case. You can also check out the <a href="https://forge.rust-lang.org/compiler/reviews.html?highlight=revert#reverts">revert policy</a> on
Forge docs (which is mainly targeted for reviewers, but contains useful info for PR authors too).</p>
<p>If the PR contains huge changes, it can be challenging to revert, making it harder to review
incremental fixes in subsequent updates. Or if certain code in that PR is heavily depended upon by
subsequent PRs, reverting it can become difficult.</p>
<p>In such cases, we can identify the problematic code and disable it for some input, as shown in <a href="https://github.com/rust-lang/rust/pull/128271">#128271</a>.</p>
<p>For MIR optimizations, we can also use the <code>-Zunsound-mir-opt</code> option to gate the mir-opt, as shown
in <a href="https://github.com/rust-lang/rust/pull/132356">#132356</a>.</p>
<h2 id="external-dependencies"><a class="header" href="#external-dependencies">External dependencies</a></h2>
<p>This section has moved to <a href="./external-repos.html">"Using External Repositories"</a>.</p>
<h2 id="writing-documentation"><a class="header" href="#writing-documentation">Writing documentation</a></h2>
<p>Documentation improvements are very welcome. The source of <code>doc.rust-lang.org</code>
is located in <a href="https://github.com/rust-lang/rust/tree/master/src/doc"><code>src/doc</code></a> in the tree, and standard API documentation is generated
from the source code itself (e.g. <a href="https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1"><code>library/std/src/lib.rs</code></a>). Documentation pull requests
function in the same way as other pull requests.</p>
<p>To find documentation-related issues, use the <a href="https://github.com/rust-lang/rust/issues?q=is%3Aopen%20is%3Aissue%20label%3AA-docs">A-docs label</a>.</p>
<p>You can find documentation style guidelines in <a href="https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text">RFC 1574</a>.</p>
<p>To build the standard library documentation, use <code>x doc --stage 1 library --open</code>.
To build the documentation for a book (e.g. the unstable book), use <code>x doc src/doc/unstable-book.</code>
Results should appear in <code>build/host/doc</code>, as well as automatically open in your default browser.
See <a href="./building/compiler-documenting.html#building-documentation">Building Documentation</a> for more
information.</p>
<p>You can also use <code>rustdoc</code> directly to check small fixes. For example,
<code>rustdoc src/doc/reference.md</code> will render reference to <code>doc/reference.html</code>.
The CSS might be messed up, but you can verify that the HTML is right.</p>
<h3 id="contributing-to-rustc-dev-guide"><a class="header" href="#contributing-to-rustc-dev-guide">Contributing to rustc-dev-guide</a></h3>
<p>Contributions to the <a href="https://rustc-dev-guide.rust-lang.org/">rustc-dev-guide</a> are always welcome, and can be made directly at
<a href="https://github.com/rust-lang/rustc-dev-guide">the rust-lang/rustc-dev-guide repo</a>.
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!</p>
<p>Just a few things to keep in mind:</p>
<ul>
<li>
<p>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.</p>
</li>
<li>
<p>When contributing text to the guide, please contextualize the information with some time period
and/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:</p>
<ul>
<li>
<p>A reason for why the data may be out of date other than "change",
as change is a constant across the project.</p>
</li>
<li>
<p>The date the comment was added, e.g. instead of writing <em>"Currently, ..."</em>
or <em>"As of now, ..."</em>,
consider adding the date, in one of the following formats:</p>
<ul>
<li>Jan 2021</li>
<li>January 2021</li>
<li>jan 2021</li>
<li>january 2021</li>
</ul>
<p>There is a CI action (in <code>.github/workflows/date-check.yml</code>)
that generates a monthly report showing those that are over 6 months old
(<a href="https://github.com/rust-lang/rustc-dev-guide/issues/2052">example</a>).</p>
<p>For the action to pick the date,
add a special annotation before specifying the date:</p>
<pre><code class="language-md">&lt;!-- date-check --&gt; Apr 2025
</code></pre>
<p>Example:</p>
<pre><code class="language-md">As of &lt;!-- date-check --&gt; Apr 2025, the foo did the bar.
</code></pre>
<p>For cases where the date should not be part of the visible rendered output,
use the following instead:</p>
<pre><code class="language-md">&lt;!-- date-check: Apr 2025 --&gt;
</code></pre>
</li>
<li>
<p>A link to a relevant WG, tracking issue, <code>rustc</code> rustdoc page, or similar, that may provide
further explanation for the change process or a way to verify that the information is not
outdated.</p>
</li>
</ul>
</li>
<li>
<p>If a text grows rather long (more than a few page scrolls) or complicated (more than four
subsections),
it might benefit from having a Table of Contents at the beginning,
which you can auto-generate by including the <code>&lt;!-- toc --&gt;</code> marker at the top.</p>
</li>
</ul>
<h2 id="issue-triage"><a class="header" href="#issue-triage">Issue triage</a></h2>
<p>Please see <a href="https://forge.rust-lang.org/release/issue-triaging.html">https://forge.rust-lang.org/release/issue-triaging.html</a>.</p>
<h3 id="rfcbot-labels"><a class="header" href="#rfcbot-labels">Rfcbot labels</a></h3>
<p><a href="https://github.com/anp/rfcbot-rs/">rfcbot</a> uses its own labels for tracking the process of coordinating
asynchronous decisions, such as approving or rejecting a change.
This is used for <a href="https://github.com/rust-lang/rfcs">RFCs</a>, issues, and pull requests.</p>
<div class="table-wrapper"><table><thead><tr><th>Labels</th><th>Color</th><th>Description</th></tr></thead><tbody>
<tr><td><a href="https://github.com/rust-lang/rust/labels/proposed-final-comment-period">proposed-final-comment-period</a></td><td><span class="label-color" style="background-color:#ededed;"> </span> Gray</td><td>Currently awaiting signoff of all team members in order to enter the final comment period.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rust/labels/disposition-merge">disposition-merge</a></td><td><span class="label-color" style="background-color:#008800;"> </span> Green</td><td>Indicates the intent is to merge the change.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rust/labels/disposition-close">disposition-close</a></td><td><span class="label-color" style="background-color:#dd0000;"> </span> Red</td><td>Indicates the intent is to not accept the change and close it.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rust/labels/disposition-postpone">disposition-postpone</a></td><td><span class="label-color" style="background-color:#ededed;"> </span> Gray</td><td>Indicates the intent is to not accept the change at this time and postpone it to a later date.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rust/labels/final-comment-period">final-comment-period</a></td><td><span class="label-color" style="background-color:#1e76d9;"> </span> Blue</td><td>Currently soliciting final comments before merging or closing.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rust/labels/finished-final-comment-period">finished-final-comment-period</a></td><td><span class="label-color" style="background-color:#f9e189;"> </span> Light Yellow</td><td>The final comment period has concluded, and the issue will be merged or closed.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rfcs/labels/postponed">postponed</a></td><td><span class="label-color" style="background-color:#fbca04;"> </span> Yellow</td><td>The issue has been postponed.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rfcs/labels/closed">closed</a></td><td><span class="label-color" style="background-color:#dd0000;"> </span> Red</td><td>The issue has been rejected.</td></tr>
<tr><td><a href="https://github.com/rust-lang/rfcs/labels/to-announce">to-announce</a></td><td><span class="label-color" style="background-color:#ededed;"> </span> Gray</td><td>Issues that have finished their final-comment-period and should be publicly announced. Note: the rust-lang/rust repository uses this label differently, to announce issues at the triage meetings.</td></tr>
</tbody></table>
</div>
<h2 id="helpful-links-and-information"><a class="header" href="#helpful-links-and-information">Helpful links and information</a></h2>
<p>This section has moved to the <a href="about-this-guide.html#other-places-to-find-information">"About this guide"</a> chapter.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="crates-io.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="compiler-team.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="crates-io.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="compiler-team.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
<script src="mermaid.min.js"></script>
<script src="mermaid-init.js"></script>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink