implementing_new_features.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Implementing new language features - 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/implementing_new_features.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="implementing-new-language-features"><a class="header" href="#implementing-new-language-features">Implementing new language features</a></h1>
 <ul>
 <li><a href="#the-rfcbot-fcp-process">The @rfcbot FCP process</a></li>
 <li><a href="#the-logistics-of-writing-features">The logistics of writing features</a>
 <ul>
 <li><a href="#warning-cycles">Warning Cycles</a></li>
 <li><a href="#stability">Stability</a></li>
 <li><a href="#tracking-issues">Tracking Issues</a></li>
 </ul>
 </li>
 <li><a href="#stability-in-code">Stability in code</a></li>
 </ul>
 <p>When you want to implement a new significant feature in the compiler,
 you need to go through this process to make sure everything goes
 smoothly.</p>
 <p><strong>NOTE: this section is for <em>language</em> features, not <em>library</em> features,
 which use <a href="./stability.html">a different process</a>.</strong></p>
 <p>See also <a href="https://lang-team.rust-lang.org/how_to/propose.html">the Rust Language Design Team's procedures</a> for
 proposing changes to the language.</p>
 <h2 id="the-rfcbot-fcp-process"><a class="header" href="#the-rfcbot-fcp-process">The @rfcbot FCP process</a></h2>
 <p>When the change is small and uncontroversial, then it can be done
 with just writing a PR and getting an r+ from someone who knows that
 part of the code. However, if the change is potentially controversial,
 it would be a bad idea to push it without consensus from the rest
 of the team (both in the "distributed system" sense to make sure
 you don't break anything you don't know about, and in the social
 sense to avoid PR fights).</p>
 <p>If such a change seems to be too small to require a full formal RFC process
 (e.g., a small standard library addition, a big refactoring of the code, a
 "technically-breaking" change, or a "big bugfix" that basically amounts to a
 small feature) but is still too controversial or big to get by with a single r+,
 you can propose a final comment period (FCP). Or, if you're not on the relevant
 team (and thus don't have @rfcbot permissions), ask someone who is to start one;
 unless they have a concern themselves, they should.</p>
 <p>Again, the FCP process is only needed if you need consensus – if you
 don't think anyone would have a problem with your change, it's OK to
 get by with only an r+. For example, it is OK to add or modify
 unstable command-line flags or attributes without an FCP for
 compiler development or standard library use, as long as you don't
 expect them to be in wide use in the nightly ecosystem.
 Some teams have lighter weight processes that they use in scenarios
 like this; for example, the compiler team recommends
 filing a Major Change Proposal (<a href="https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#how-do-i-submit-an-mcp">MCP</a>) as a lightweight way to
 garner support and feedback without requiring full consensus.</p>
 <p>You don't need to have the implementation fully ready for r+ to propose an FCP,
 but it is generally a good idea to have at least a proof
 of concept so that people can see what you are talking about.</p>
 <p>When an FCP is proposed, it requires all members of the team to sign off the
 FCP. After they all do so, there's a 10-day-long "final comment period" (hence
 the name) where everybody can comment, and if no concerns are raised, the
 PR/issue gets FCP approval.</p>
 <h2 id="the-logistics-of-writing-features"><a class="header" href="#the-logistics-of-writing-features">The logistics of writing features</a></h2>
 <p>There are a few "logistic" hoops you might need to go through in
 order to implement a feature in a working way.</p>
 <h3 id="warning-cycles"><a class="header" href="#warning-cycles">Warning Cycles</a></h3>
 <p>In some cases, a feature or bugfix might break some existing programs
 in some edge cases. In that case, you might want to do a crater run
 to assess the impact and possibly add a future-compatibility lint,
 similar to those used for
 <a href="diagnostics.html#edition-gated-lints">edition-gated lints</a>.</p>
 <h3 id="stability"><a class="header" href="#stability">Stability</a></h3>
 <p>We <a href="https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md">value the stability of Rust</a>. Code that works and runs on stable
 should (mostly) not break. Because of that, we don't want to release
 a feature to the world with only team consensus and code review -
 we want to gain real-world experience on using that feature on nightly,
 and we might want to change the feature based on that experience.</p>
 <p>To allow for that, we must make sure users don't accidentally depend
 on that new feature - otherwise, especially if experimentation takes
 time or is delayed and the feature takes the trains to stable,
 it would end up de facto stable and we'll not be able to make changes
 in it without breaking people's code.</p>
 <p>The way we do that is that we make sure all new features are feature
 gated - they can't be used without enabling a feature gate
 (<code>#[feature(foo)]</code>), which can't be done in a stable/beta compiler.
 See the <a href="#stability-in-code">stability in code</a> section for the technical details.</p>
 <p>Eventually, after we gain enough experience using the feature,
 make the necessary changes, and are satisfied, we expose it to
 the world using the stabilization process described <a href="./stabilization_guide.html">here</a>.
 Until then, the feature is not set in stone: every part of the
 feature can be changed, or the feature might be completely
 rewritten or removed. Features are not supposed to gain tenure
 by being unstable and unchanged for a year.</p>
 <h3 id="tracking-issues"><a class="header" href="#tracking-issues">Tracking Issues</a></h3>
 <p>To keep track of the status of an unstable feature, the
 experience we get while using it on nightly, and of the
 concerns that block its stabilization, every feature-gate
 needs a tracking issue. General discussions about the feature should be done on the tracking issue.</p>
 <p>For features that have an RFC, you should use the RFC's
 tracking issue for the feature.</p>
 <p>For other features, you'll have to make a tracking issue
 for that feature. The issue title should be "Tracking issue
 for YOUR FEATURE". Use the <a href="https://github.com/rust-lang/rust/issues/new?template=tracking_issue.md">"Tracking Issue" issue template</a>.</p>
 <h2 id="stability-in-code"><a class="header" href="#stability-in-code">Stability in code</a></h2>
 <p>The below steps needs to be followed in order to implement
 a new unstable feature:</p>
 <ol>
 <li>
 <p>Open a <a href="#tracking-issues">tracking issue</a> -
 if you have an RFC, you can use the tracking issue for the RFC.</p>
 <p>The tracking issue should be labeled with at least <code>C-tracking-issue</code>.
 For a language feature, a label <code>F-feature_name</code> should be added as well.</p>
 </li>
 <li>
 <p>Pick a name for the feature gate (for RFCs, use the name
 in the RFC).</p>
 </li>
 <li>
 <p>Add the feature name to <code>rustc_span/src/symbol.rs</code> in the <code>Symbols {...}</code> block.</p>
 <p>Note that this block must be in alphabetical order.</p>
 </li>
 <li>
 <p>Add a feature gate declaration to <code>rustc_feature/src/unstable.rs</code> in the unstable
 <code>declare_features</code> block.</p>
 <pre><code class="language-rust ignore">/// description of feature
 (unstable, $feature_name, "CURRENT_RUSTC_VERSION", Some($tracking_issue_number))</code></pre>
 <p>If you haven't yet
 opened a tracking issue (e.g. because you want initial feedback on whether the feature is likely
 to be accepted), you can temporarily use <code>None</code> - but make sure to update it before the PR is
 merged!</p>
 <p>For example:</p>
 <pre><code class="language-rust ignore">/// Allows defining identifiers beyond ASCII.
 (unstable, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467), None),</code></pre>
 <p>Features can be marked as incomplete, and trigger the warn-by-default <a href="https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features"><code>incomplete_features</code>
 lint</a>
 by setting their type to <code>incomplete</code>:</p>
 <pre><code class="language-rust ignore">/// Allows deref patterns.
 (incomplete, deref_patterns, "CURRENT_RUSTC_VERSION", Some(87121), None),</code></pre>
 <p>To avoid <a href="https://bors.tech/essay/2017/02/02/pitch/">semantic merge conflicts</a>, please use <code>CURRENT_RUSTC_VERSION</code> instead of <code>1.70</code> or
 another explicit version number.</p>
 </li>
 <li>
 <p>Prevent usage of the new feature unless the feature gate is set.
 You can check it in most places in the compiler using the
 expression <code>tcx.features().$feature_name()</code></p>
 <p>If the feature gate is not set, you should either maintain
 the pre-feature behavior or raise an error, depending on
 what makes sense. Errors should generally use <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/fn.feature_err.html"><code>rustc_session::parse::feature_err</code></a>.
 For an example of adding an error, see <a href="https://github.com/rust-lang/rust/pull/81015">#81015</a>.</p>
 <p>For features introducing new syntax, pre-expansion gating should be used instead.
 During parsing, when the new syntax is parsed, the symbol must be inserted to the
 current crate's <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html"><code>GatedSpans</code></a> via <code>self.sess.gated_span.gate(sym::my_feature, span)</code>.</p>
 <p>After being inserted to the gated spans, the span must be checked in the
 <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_passes/feature_gate/fn.check_crate.html"><code>rustc_ast_passes::feature_gate::check_crate</code></a> function, which actually denies
 features. Exactly how it is gated depends on the exact type of feature, but most
 likely will use the <code>gate_all!()</code> macro.</p>
 </li>
 <li>
 <p>Add a test to ensure the feature cannot be used without
 a feature gate, by creating <code>tests/ui/feature-gates/feature-gate-$feature_name.rs</code>.
 You can generate the corresponding <code>.stderr</code> file by running <code>./x test  tests/ui/feature-gates/ --bless</code>.</p>
 </li>
 <li>
 <p>Add a section to the unstable book, in
 <code>src/doc/unstable-book/src/language-features/$feature_name.md</code>.</p>
 </li>
 <li>
 <p>Write a lot of tests for the new feature, preferably in <code>tests/ui/$feature_name/</code>.
 PRs without tests will not be accepted!</p>
 </li>
 <li>
 <p>Get your PR reviewed and land it. You have now successfully
 implemented a feature in Rust!</p>
 </li>
 </ol>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="walkthrough.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="stability.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="walkthrough.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="stability.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>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Implementing new language features - 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/implementing_new_features.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="implementing-new-language-features"><a class="header" href="#implementing-new-language-features">Implementing new language features</a></h1>
	<ul>
	<li><a href="#the-rfcbot-fcp-process">The @rfcbot FCP process</a></li>
	<li><a href="#the-logistics-of-writing-features">The logistics of writing features</a>
	<ul>
	<li><a href="#warning-cycles">Warning Cycles</a></li>
	<li><a href="#stability">Stability</a></li>
	<li><a href="#tracking-issues">Tracking Issues</a></li>
	</ul>
	</li>
	<li><a href="#stability-in-code">Stability in code</a></li>
	</ul>
	<p>When you want to implement a new significant feature in the compiler,
	you need to go through this process to make sure everything goes
	smoothly.</p>
	<p><strong>NOTE: this section is for <em>language</em> features, not <em>library</em> features,
	which use <a href="./stability.html">a different process</a>.</strong></p>
	<p>See also <a href="https://lang-team.rust-lang.org/how_to/propose.html">the Rust Language Design Team's procedures</a> for
	proposing changes to the language.</p>
	<h2 id="the-rfcbot-fcp-process"><a class="header" href="#the-rfcbot-fcp-process">The @rfcbot FCP process</a></h2>
	<p>When the change is small and uncontroversial, then it can be done
	with just writing a PR and getting an r+ from someone who knows that
	part of the code. However, if the change is potentially controversial,
	it would be a bad idea to push it without consensus from the rest
	of the team (both in the "distributed system" sense to make sure
	you don't break anything you don't know about, and in the social
	sense to avoid PR fights).</p>
	<p>If such a change seems to be too small to require a full formal RFC process
	(e.g., a small standard library addition, a big refactoring of the code, a
	"technically-breaking" change, or a "big bugfix" that basically amounts to a
	small feature) but is still too controversial or big to get by with a single r+,
	you can propose a final comment period (FCP). Or, if you're not on the relevant
	team (and thus don't have @rfcbot permissions), ask someone who is to start one;
	unless they have a concern themselves, they should.</p>
	<p>Again, the FCP process is only needed if you need consensus – if you
	don't think anyone would have a problem with your change, it's OK to
	get by with only an r+. For example, it is OK to add or modify
	unstable command-line flags or attributes without an FCP for
	compiler development or standard library use, as long as you don't
	expect them to be in wide use in the nightly ecosystem.
	Some teams have lighter weight processes that they use in scenarios
	like this; for example, the compiler team recommends
	filing a Major Change Proposal (<a href="https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#how-do-i-submit-an-mcp">MCP</a>) as a lightweight way to
	garner support and feedback without requiring full consensus.</p>
	<p>You don't need to have the implementation fully ready for r+ to propose an FCP,
	but it is generally a good idea to have at least a proof
	of concept so that people can see what you are talking about.</p>
	<p>When an FCP is proposed, it requires all members of the team to sign off the
	FCP. After they all do so, there's a 10-day-long "final comment period" (hence
	the name) where everybody can comment, and if no concerns are raised, the
	PR/issue gets FCP approval.</p>
	<h2 id="the-logistics-of-writing-features"><a class="header" href="#the-logistics-of-writing-features">The logistics of writing features</a></h2>
	<p>There are a few "logistic" hoops you might need to go through in
	order to implement a feature in a working way.</p>
	<h3 id="warning-cycles"><a class="header" href="#warning-cycles">Warning Cycles</a></h3>
	<p>In some cases, a feature or bugfix might break some existing programs
	in some edge cases. In that case, you might want to do a crater run
	to assess the impact and possibly add a future-compatibility lint,
	similar to those used for
	<a href="diagnostics.html#edition-gated-lints">edition-gated lints</a>.</p>
	<h3 id="stability"><a class="header" href="#stability">Stability</a></h3>
	<p>We <a href="https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md">value the stability of Rust</a>. Code that works and runs on stable
	should (mostly) not break. Because of that, we don't want to release
	a feature to the world with only team consensus and code review -
	we want to gain real-world experience on using that feature on nightly,
	and we might want to change the feature based on that experience.</p>
	<p>To allow for that, we must make sure users don't accidentally depend
	on that new feature - otherwise, especially if experimentation takes
	time or is delayed and the feature takes the trains to stable,
	it would end up de facto stable and we'll not be able to make changes
	in it without breaking people's code.</p>
	<p>The way we do that is that we make sure all new features are feature
	gated - they can't be used without enabling a feature gate
	(<code>#[feature(foo)]</code>), which can't be done in a stable/beta compiler.
	See the <a href="#stability-in-code">stability in code</a> section for the technical details.</p>
	<p>Eventually, after we gain enough experience using the feature,
	make the necessary changes, and are satisfied, we expose it to
	the world using the stabilization process described <a href="./stabilization_guide.html">here</a>.
	Until then, the feature is not set in stone: every part of the
	feature can be changed, or the feature might be completely
	rewritten or removed. Features are not supposed to gain tenure
	by being unstable and unchanged for a year.</p>
	<h3 id="tracking-issues"><a class="header" href="#tracking-issues">Tracking Issues</a></h3>
	<p>To keep track of the status of an unstable feature, the
	experience we get while using it on nightly, and of the
	concerns that block its stabilization, every feature-gate
	needs a tracking issue. General discussions about the feature should be done on the tracking issue.</p>
	<p>For features that have an RFC, you should use the RFC's
	tracking issue for the feature.</p>
	<p>For other features, you'll have to make a tracking issue
	for that feature. The issue title should be "Tracking issue
	for YOUR FEATURE". Use the <a href="https://github.com/rust-lang/rust/issues/new?template=tracking_issue.md">"Tracking Issue" issue template</a>.</p>
	<h2 id="stability-in-code"><a class="header" href="#stability-in-code">Stability in code</a></h2>
	<p>The below steps needs to be followed in order to implement
	a new unstable feature:</p>
	<ol>
	<li>
	<p>Open a <a href="#tracking-issues">tracking issue</a> -
	if you have an RFC, you can use the tracking issue for the RFC.</p>
	<p>The tracking issue should be labeled with at least <code>C-tracking-issue</code>.
	For a language feature, a label <code>F-feature_name</code> should be added as well.</p>
	</li>
	<li>
	<p>Pick a name for the feature gate (for RFCs, use the name
	in the RFC).</p>
	</li>
	<li>
	<p>Add the feature name to <code>rustc_span/src/symbol.rs</code> in the <code>Symbols {...}</code> block.</p>
	<p>Note that this block must be in alphabetical order.</p>
	</li>
	<li>
	<p>Add a feature gate declaration to <code>rustc_feature/src/unstable.rs</code> in the unstable
	<code>declare_features</code> block.</p>
	<pre><code class="language-rust ignore">/// description of feature
	(unstable, $feature_name, "CURRENT_RUSTC_VERSION", Some($tracking_issue_number))</code></pre>
	<p>If you haven't yet
	opened a tracking issue (e.g. because you want initial feedback on whether the feature is likely
	to be accepted), you can temporarily use <code>None</code> - but make sure to update it before the PR is
	merged!</p>
	<p>For example:</p>
	<pre><code class="language-rust ignore">/// Allows defining identifiers beyond ASCII.
	(unstable, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467), None),</code></pre>
	<p>Features can be marked as incomplete, and trigger the warn-by-default <a href="https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features"><code>incomplete_features</code>
	lint</a>
	by setting their type to <code>incomplete</code>:</p>
	<pre><code class="language-rust ignore">/// Allows deref patterns.
	(incomplete, deref_patterns, "CURRENT_RUSTC_VERSION", Some(87121), None),</code></pre>
	<p>To avoid <a href="https://bors.tech/essay/2017/02/02/pitch/">semantic merge conflicts</a>, please use <code>CURRENT_RUSTC_VERSION</code> instead of <code>1.70</code> or
	another explicit version number.</p>
	</li>
	<li>
	<p>Prevent usage of the new feature unless the feature gate is set.
	You can check it in most places in the compiler using the
	expression <code>tcx.features().$feature_name()</code></p>
	<p>If the feature gate is not set, you should either maintain
	the pre-feature behavior or raise an error, depending on
	what makes sense. Errors should generally use <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/fn.feature_err.html"><code>rustc_session::parse::feature_err</code></a>.
	For an example of adding an error, see <a href="https://github.com/rust-lang/rust/pull/81015">#81015</a>.</p>
	<p>For features introducing new syntax, pre-expansion gating should be used instead.
	During parsing, when the new syntax is parsed, the symbol must be inserted to the
	current crate's <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html"><code>GatedSpans</code></a> via <code>self.sess.gated_span.gate(sym::my_feature, span)</code>.</p>
	<p>After being inserted to the gated spans, the span must be checked in the
	<a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_passes/feature_gate/fn.check_crate.html"><code>rustc_ast_passes::feature_gate::check_crate</code></a> function, which actually denies
	features. Exactly how it is gated depends on the exact type of feature, but most
	likely will use the <code>gate_all!()</code> macro.</p>
	</li>
	<li>
	<p>Add a test to ensure the feature cannot be used without
	a feature gate, by creating <code>tests/ui/feature-gates/feature-gate-$feature_name.rs</code>.
	You can generate the corresponding <code>.stderr</code> file by running <code>./x test tests/ui/feature-gates/ --bless</code>.</p>
	</li>
	<li>
	<p>Add a section to the unstable book, in
	<code>src/doc/unstable-book/src/language-features/$feature_name.md</code>.</p>
	</li>
	<li>
	<p>Write a lot of tests for the new feature, preferably in <code>tests/ui/$feature_name/</code>.
	PRs without tests will not be accepted!</p>
	</li>
	<li>
	<p>Get your PR reviewed and land it. You have now successfully
	implemented a feature in Rust!</p>
	</li>
	</ol>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="walkthrough.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="stability.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="walkthrough.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="stability.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>