| <!DOCTYPE HTML> |
| <html lang="en" class="light sidebar-visible" dir="ltr"> |
| <head> |
| <!-- Book generated using mdBook --> |
| <meta charset="UTF-8"> |
| <title>Unstable features - Cargo Contributor Guide</title> |
| |
| |
| <!-- Custom HTML head --> |
| |
| <meta name="description" content=""> |
| <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"; |
| window.path_to_searchindex_js = "../searchindex.js"; |
| </script> |
| <!-- Start loading toc.js asap --> |
| <script src="../toc.js"></script> |
| </head> |
| <body> |
| <div id="mdbook-help-container"> |
| <div id="mdbook-help-popup"> |
| <h2 class="mdbook-help-title">Keyboard shortcuts</h2> |
| <div> |
| <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p> |
| <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p> |
| <p>Press <kbd>?</kbd> to show this help</p> |
| <p>Press <kbd>Esc</kbd> to hide this help</p> |
| </div> |
| </div> |
| </div> |
| <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 = false; |
| } |
| if (sidebar === 'visible') { |
| sidebar_toggle.checked = true; |
| } else { |
| html.classList.remove('sidebar-visible'); |
| } |
| </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 (`/`)" 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">Cargo Contributor 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/cargo/tree/master/src/doc/contrib/src" 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/cargo/edit/master/src/doc/contrib/src/process/unstable.md" title="Suggest an edit" aria-label="Suggest an edit" rel="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"> |
| <div class="search-wrapper"> |
| <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> |
| <div class="spinner-wrapper"> |
| <i class="fa fa-spinner fa-spin"></i> |
| </div> |
| </div> |
| </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="unstable-features"><a class="header" href="#unstable-features">Unstable features</a></h1> |
| <p>Most new features should go through the unstable process. This means that the |
| feature will only be usable on the nightly channel, and requires a specific |
| opt-in by the user. Small changes can skip this process, but please consult |
| with the Cargo team first.</p> |
| <h2 id="tracking-issues"><a class="header" href="#tracking-issues">Tracking issues</a></h2> |
| <p>Each unstable feature should get a <a href="https://github.com/rust-lang/cargo/labels/C-tracking-issue">tracking issue</a>. These issues are |
| typically created when a PR is close to being merged, or soon after it is |
| merged. Use the <a href="https://github.com/rust-lang/cargo/issues/new?labels=C-tracking-issue&template=tracking_issue.yml">tracking issue template</a> when creating a tracking issue.</p> |
| <p>Larger features should also get a new label in the issue tracker so that when |
| issues are filed, they can be easily tied together. Typically this would be |
| one of the <code>Z-</code> prefixed labels for nightly features.</p> |
| <p>When opening a tracking issue, be sure to also add an <code>S-</code> status label to |
| indicate what needs to happen for it to move forward:</p> |
| <ul> |
| <li><a href="https://github.com/rust-lang/cargo/labels/S-needs-mentor">S-needs-mentor</a> — The feature isn’t yet implemented, and needs a Cargo |
| team member to commit to helping guide and review the implementation.</li> |
| <li><a href="https://github.com/rust-lang/cargo/labels/S-accepted">S-accepted</a> — The feature isn’t yet implemented, and has a Cargo team |
| member willing to help review the implementation.</li> |
| <li><a href="https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback">S-waiting-on-feedback</a> — After the feature has been implemented, this |
| label indicates that it is waiting on community feedback for bugs or design |
| concerns.</li> |
| </ul> |
| <p>Tracking issues may have multiple status labels if necessary, for example if |
| something is only partially implemented, it may have both |
| <a href="https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback">S-waiting-on-feedback</a> (for what is implemented) and <a href="https://github.com/rust-lang/cargo/labels/S-needs-mentor">S-needs-mentor</a> or |
| <a href="https://github.com/rust-lang/cargo/labels/S-accepted">S-accepted</a> to finish the rest of the work.</p> |
| <h2 id="implementation"><a class="header" href="#implementation">Implementation</a></h2> |
| <p>See <a href="working-on-cargo.html">Working on Cargo</a>.</p> |
| <p>During implementation and testing, you may find reasons to deviate from the RFC. |
| Please call these out in the tracking issue, with links to more information justifying the change |
| (e.g. see <a href="https://github.com/rust-lang/cargo/issues/8415">workspace inheritance tracking issue</a>).</p> |
| <h4 id="unstable-feature-opt-in"><a class="header" href="#unstable-feature-opt-in">Unstable feature opt-in</a></h4> |
| <p>For features that require behavior changes or new syntax in <code>Cargo.toml</code>, then |
| it will need a <code>cargo-features</code> value placed at the top of <code>Cargo.toml</code> to |
| enable it. The process for adding a new feature is described in the |
| <a href="https://github.com/rust-lang/cargo/blob/master/src/cargo/core/features.rs"><code>features</code> module</a>. Code that implements the feature will need to manually |
| check that the feature is enabled for the current manifest.</p> |
| <p>For features that add new command-line flags, config options, or environment |
| variables, then the <code>-Z</code> flags will be needed to enable them. The <a href="https://github.com/rust-lang/cargo/blob/master/src/cargo/core/features.rs"><code>features</code> |
| module</a> also describes how to add these. New flags should use the |
| <code>fail_if_stable_opt</code> method to check if the <code>-Z unstable-options</code> flag has |
| been passed.</p> |
| <h4 id="unstable-documentation"><a class="header" href="#unstable-documentation">Unstable documentation</a></h4> |
| <p>Every unstable feature should have a section added to the <a href="https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md">unstable chapter</a> |
| describing how to use the feature. |
| This can also serve as a place for the final documentation to live until its stabilized.</p> |
| <h2 id="pre-stabilization"><a class="header" href="#pre-stabilization">Pre-Stabilization</a></h2> |
| <p>Once an unstable feature is “complete”, the search for users to test |
| and give feedback begins:</p> |
| <ol> |
| <li>Write up test instructions for users, summarizing where the feature is useful, how to use it (with links to the unstable documentation), and if there are any areas of particular concern</li> |
| </ol> |
| <ul> |
| <li>This could be on the tracking issue or in a dedicated issue for feedback</li> |
| <li>e.g. <a href="https://github.com/rust-lang/cargo/blob/6d6dd9d9be9c91390da620adf43581619c2fa90e/src/doc/src/reference/unstable.md#testing-notes">workspace inheritance testing notes</a></li> |
| </ul> |
| <ol start="2"> |
| <li>Call for testing</li> |
| </ol> |
| <ul> |
| <li>In the RFC, link to the test instructions and label it with <code>call-for-testing</code> to be picked up by <a href="https://this-week-in-rust.org/">This Week in Rust</a> |
| <ul> |
| <li>If there is not an RFC, a pull request should be made to the <a href="https://github.com/rust-lang/this-week-in-rust">TWiR repo</a> |
| adding the feature to the <code>Call for Testing</code> section (<a href="https://github.com/rust-lang/this-week-in-rust/pull/3256">example</a>).</li> |
| </ul> |
| </li> |
| <li>Post on various Rust communities (<a href="https://www.reddit.com/r/rust/">rust subreddit</a>, <a href="https://users.rust-lang.org/">users</a>, <a href="https://internals.rust-lang.org/">internals</a>, etc)</li> |
| <li>e.g. <a href="https://www.reddit.com/r/rust/comments/uo8zeh/help_test_workspace_inheritance_in_preparation/">reddit post</a>, <a href="https://users.rust-lang.org/t/help-test-workspace-inheritance-in-preparation-for-stablization/75582">users post</a>, <a href="https://internals.rust-lang.org/t/help-test-workspace-inheritance-in-preparation-for-stablization/16618">internals post</a></li> |
| </ul> |
| <h2 id="stabilization"><a class="header" href="#stabilization">Stabilization</a></h2> |
| <p>After some period of time, typically measured in months, the feature can be |
| considered to be stabilized. The feature should not have any significant known |
| bugs or issues, and any design concerns should be resolved.</p> |
| <p>The stabilization process depends on the kind of feature. For smaller |
| features, you can leave a comment on the tracking issue expressing interest in |
| stabilizing it. It can usually help to indicate that the feature has received |
| some real-world testing, and has exhibited some demand for broad use.</p> |
| <p>For larger features that have not gone through the <a href="https://github.com/rust-lang/rfcs/">RFC process</a>, then an RFC |
| to call for stabilization might be warranted. This gives the community a final |
| chance to provide feedback about the proposed design.</p> |
| <p>For a small feature, or one that has already gone through the RFC process, a |
| Cargo Team member may decide to call for a “final comment period” using |
| <a href="https://github.com/rust-lang/rfcbot-rs">rfcbot</a>. This is a public signal that a major change is being made, and gives |
| the Cargo Team members an opportunity to confirm or block the change. This |
| process can take a few days or weeks, or longer if a concern is raised.</p> |
| <p>Once the stabilization has been approved, the person who called for |
| stabilization should prepare a PR to stabilize the feature. This PR should:</p> |
| <ul> |
| <li>Flip the feature to stable in the <a href="https://github.com/rust-lang/cargo/blob/master/src/cargo/core/features.rs"><code>features</code> module</a>.</li> |
| <li>Remove any unstable checks that aren’t automatically handled by the feature |
| system.</li> |
| <li>Move the documentation from the <a href="https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md">unstable chapter</a> into the appropriate |
| places in the Cargo book and man pages.</li> |
| <li>Remove the <code>-Z</code> flags and help message if applicable.</li> |
| <li>Update all tests to remove nightly checks.</li> |
| <li>Tag the PR with <a href="https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes">relnotes</a> label if it seems important enough to highlight |
| in the <a href="https://github.com/rust-lang/rust/blob/master/RELEASES.md">Rust release notes</a>.</li> |
| </ul> |
| |
| </main> |
| |
| <nav class="nav-wrapper" aria-label="Page navigation"> |
| <!-- Mobile navigation buttons --> |
| <a rel="prev" href="../process/rfc.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="../process/security.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="../process/rfc.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="../process/security.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 --> |
| |
| |
| |
| </div> |
| </body> |
| </html> |
