| <!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> |
| <ul> |
| <li><a href="#-note-where-to-contribute-rustc-dev-guide-changes">⚠️ Note: Where to contribute <code>rustc-dev-guide</code> changes</a></li> |
| </ul> |
| </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"><!-- date-check --> Apr 2025 |
| </code></pre> |
| <p>Example:</p> |
| <pre><code class="language-md">As of <!-- date-check --> 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"><!-- date-check: Apr 2025 --> |
| </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><!-- toc --></code> marker at the top.</p> |
| </li> |
| </ul> |
| <h4 id="-note-where-to-contribute-rustc-dev-guide-changes"><a class="header" href="#-note-where-to-contribute-rustc-dev-guide-changes">⚠️ Note: Where to contribute <code>rustc-dev-guide</code> changes</a></h4> |
| <p>For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so, see <a href="https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes">the rustc-dev-guide working group documentation</a>.</p> |
| <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> |
