blob: 3cd01082cf0ace6b9dabcde1623637b726db6dc2 [file] [log] [blame] [edit]
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Issue Tracker - 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/issues.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="issue-tracker"><a class="header" href="#issue-tracker">Issue Tracker</a></h1>
<p>Cargo’s issue tracker is located at
<a href="https://github.com/rust-lang/cargo/issues/">https://github.com/rust-lang/cargo/issues/</a>. This is the primary spot where
we track bugs and small feature requests. See <a href="process/index.html">Process</a> for more about our
process for proposing changes.</p>
<h2 id="filing-issues"><a class="header" href="#filing-issues">Filing issues</a></h2>
<p>We can’t fix what we don’t know about, so please report problems liberally.
This includes problems with understanding the documentation, unhelpful error
messages, and unexpected behavior.</p>
<p><strong>If you think that you have identified an issue with Cargo that might
compromise its users’ security, please do not open a public issue on GitHub.
Instead, we ask you to refer to Rust’s <a href="https://www.rust-lang.org/security.html">security policy</a>.</strong></p>
<p>Opening an issue is as easy as following <a href="https://github.com/rust-lang/cargo/issues/new/choose">this link</a>. There are
several templates for different issue kinds, but if none of them fit your
issue, don’t hesitate to modify one of the templates, or click the <a href="https://github.com/rust-lang/cargo/issues/new">Open a
blank issue</a> link.</p>
<p>The Rust tools are spread across multiple repositories in the Rust
organization. It may not always be clear where to file an issue. No worries!
If you file in the wrong tracker, someone will either transfer it to the
correct one or ask you to move it. Some other repositories that may be
relevant are:</p>
<ul>
<li><a href="https://github.com/rust-lang/rust"><code>rust-lang/rust</code></a> — Home for the <a href="https://doc.rust-lang.org/rustc/"><code>rustc</code></a> compiler and <a href="https://doc.rust-lang.org/rustdoc/"><code>rustdoc</code></a>.</li>
<li><a href="https://github.com/rust-lang/rustup"><code>rust-lang/rustup</code></a> — Home for the <a href="https://rust-lang.github.io/rustup/"><code>rustup</code></a> toolchain installer.</li>
<li><a href="https://github.com/rust-lang/rustfmt"><code>rust-lang/rustfmt</code></a> — Home for the <code>rustfmt</code> tool, which also includes <code>cargo fmt</code>.</li>
<li><a href="https://github.com/rust-lang/rust-clippy"><code>rust-lang/rust-clippy</code></a> — Home for the <code>clippy</code> tool, which also includes <code>cargo clippy</code>.</li>
<li><a href="https://github.com/rust-lang/crates.io"><code>rust-lang/crates.io</code></a> — Home for the <a href="https://crates.io/">crates.io</a> website.</li>
</ul>
<p>Issues with <a href="https://doc.rust-lang.org/cargo/commands/cargo-fix.html"><code>cargo fix</code></a> can be tricky to know where they should be filed,
since the fixes are driven by <code>rustc</code>, and the front-interface is implemented
in Cargo. Feel free to file in the Cargo issue tracker, and it will get moved
to the <a href="https://github.com/rust-lang/rust"><code>rust-lang/rust</code></a> issue tracker if necessary.</p>
<h2 id="issue-labels"><a class="header" href="#issue-labels">Issue labels</a></h2>
<p><a href="https://github.com/rust-lang/cargo/labels">Issue labels</a> are very helpful to identify the types of issues and which
category they are related to.</p>
<p>Anyone can apply most labels by posting comments with a form such as:</p>
<pre><code class="language-text">@rustbot label: +A-doctests, -A-dependency-resolution
</code></pre>
<p>This example will add the <a href="https://github.com/rust-lang/cargo/labels/A-doctests"><code>A-doctests</code></a> label and remove the
<a href="https://github.com/rust-lang/cargo/labels/A-dependency-resolution"><code>A-dependency-resolution</code></a> label.</p>
<p>The labels use a naming convention with short prefixes and colors to indicate
the kind of label:</p>
<style>
.label-color {
border-radius:0.5em;
}
table td:nth-child(2) {
white-space: nowrap;
}
</style>
<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/cargo/labels?q=A">A-</a></td><td><span class="label-color" style="background-color:#fbca04;"></span> Yellow</td><td>The <strong>area</strong> of the project an issue relates to.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=beta">beta-</a></td><td><span class="label-color" style="background-color:#1e76d9;"></span> Dark Blue</td><td>Tracks changes which need to be <a href="https://forge.rust-lang.org/release/backporting.html#beta-backporting-in-rust-langcargo">backported to beta</a></td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=C">C-</a></td><td><span class="label-color" style="background-color:#f5f1fd;"></span> Light Purple</td><td>The <strong>category</strong> of an issue.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=Command">Command-</a></td><td><span class="label-color" style="background-color:#5319e7;"></span> Dark Purple</td><td>The <code>cargo</code> command it is related to.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=E">E-</a></td><td><span class="label-color" style="background-color:#02e10c;"></span> Green</td><td>The <strong>experience</strong> level necessary to fix an issue.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=I">I-</a></td><td><span class="label-color" style="background-color:#fc2929;"></span> Red</td><td>The <strong>importance</strong> of the issue.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=O">O-</a></td><td><span class="label-color" style="background-color:#7e7ec8;"></span> Purple Grey</td><td>The <strong>operating system</strong> or platform that the issue is specific to.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=P">P-</a></td><td><span class="label-color" style="background-color:#eb6420;"></span> Orange</td><td>The issue <strong>priority</strong>.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=regression">regression-</a></td><td><span class="label-color" style="background-color:#e4008a;"></span> Pink</td><td>Tracks regressions from a stable release.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes">relnotes</a></td><td><span class="label-color" style="background-color:#fad8c7;"></span> Light Orange</td><td>Marks issues or PRs that should be highlighted in the <a href="https://github.com/rust-lang/rust/blob/master/RELEASES.md">Rust release notes</a> of the next release.</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=S">S-</a></td><td>Varies</td><td>Tracks the <strong>status</strong> of issues and pull requests (see <a href="#issue-status-labels">Issue status labels</a>)</td></tr>
<tr><td><a href="https://github.com/rust-lang/cargo/labels?q=nightly">Z-</a></td><td><span class="label-color" style="background-color:#453574;"></span> Dark Blue</td><td>Unstable, <a href="https://doc.rust-lang.org/nightly/cargo/reference/unstable.html">nightly features</a>.</td></tr>
</tbody></table>
</div>
<h3 id="issue-status-labels"><a class="header" href="#issue-status-labels">Issue status labels</a></h3>
<p>The <code>S-</code> prefixed <em>status</em> labels are the primary mechanism we use to track
what is happening with an issue and what it is waiting on. The following is a
list of the status labels and what they mean. This is listed roughly in the
order that an issue might go through, though issues will often jump to
different steps, or in rare cases have multiple statuses.</p>
<ul>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-triage">S-triage</a></strong> — New issues get this label automatically assigned to them
to indicate that nobody has yet looked at them, and they need someone to
assign other labels and decide what the next step is.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-needs-info">S-needs-info</a></strong> — Needs more info, such as a reproduction or more
background for a feature request.</p>
<p>Anyone is welcome to help with providing additional info to help reproduce
or provide more detail on use cases and such. But usually this is a request
to the initial author.</p>
<p>When adding this label, there should also usually be a comment that goes
along with it stating the information requested.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-needs-team-input">S-needs-team-input</a></strong> — Needs input from team on whether/how to
proceed.</p>
<p>Here it is essentially blocked waiting for a team member to move it to the
next stage.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-needs-design">S-needs-design</a></strong> — Needs someone to work further on the design for the
feature or fix.</p>
<p>Anyone is welcome to help at this stage, but it should be clear that it is
not yet accepted. It is expected that people should contribute comments and
ideas to the issue which furthers the process of fleshing out what is
needed, or alternate ideas. This may also require reaching out to the wider
community via forums and such.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-needs-rfc">S-needs-rfc</a></strong> — Needs an <a href="https://github.com/rust-lang/rfcs/">RFC</a> before this can make more progress.</p>
<p>Anyone is welcome to help at this stage, but it should be clear that it is
not yet accepted.
See <a href="https://github.com/rust-lang/rfcs?tab=readme-ov-file#before-creating-an-rfc">Before creating an RFC</a>
for next steps.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-needs-mentor">S-needs-mentor</a></strong> — Needs a Cargo team member to commit to helping and
reviewing.</p>
<p>This is for something that is accepted, such as after an RFC or a team
discussion, or an obvious issue that just needs fixing, but no team member
is available to help or review.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-accepted">S-accepted</a></strong> — Issue or feature is accepted, and has a team member
available to help mentor or review.</p>
</li>
<li>
<p><strong><a href="https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback">S-waiting-on-feedback</a></strong> — An implemented feature is waiting on
community feedback for bugs or design concerns.</p>
<p>This is typically used on a <a href="https://github.com/rust-lang/cargo/labels/C-tracking-issue">tracking issue</a> after it has been implemented
to indicate what it is waiting on.</p>
</li>
</ul>
<h2 id="triaging-issues"><a class="header" href="#triaging-issues">Triaging issues</a></h2>
<p>Triaging issues involves processing issues to assign appropriate labels, make
sure the issue has sufficient information, and to decide the next steps.
When new issues are filed, they should automatically get the <a href="https://github.com/rust-lang/cargo/labels/S-triage">S-triage</a> label
assuming the author uses one of the templates. This helps identify which
issues have not yet been triaged.</p>
<p>There are several things to consider when triaging an issue:</p>
<ul>
<li>
<p>Is this a duplicate? Search the issue tracker (including closed issues) to
see if there is an issue with a similar or identical root cause to what is reported.
We generally focus issues around root causes so alternative solutions can be
discussed and evaluated together.
If it is obviously a duplicate, write a comment that it is a duplicate of the
other issue, and close the issue.
If it isn’t obvious that it is a duplicate, leave a comment asking the author
if the other issue covers what they reported.</p>
</li>
<li>
<p>For a bug, check if the report contains enough information to reproduce it.
If you can’t reproduce it, solicit more information from the author to
better understand the issue.
Change the label from <a href="https://github.com/rust-lang/cargo/labels/S-triage">S-triage</a> to <a href="https://github.com/rust-lang/cargo/labels/S-needs-info">S-needs-info</a> if this is the case.</p>
</li>
<li>
<p>Add labels that describe what the issue is related to.</p>
<ul>
<li>Add the appropriate <a href="https://github.com/rust-lang/cargo/labels?q=A">A-</a>, <a href="https://github.com/rust-lang/cargo/labels?q=Command">Command-</a>, <a href="https://github.com/rust-lang/cargo/labels?q=O">O-</a>, and <a href="https://github.com/rust-lang/cargo/labels?q=nightly">Z-</a> prefixed labels.</li>
<li>If this is a regression from stable, add one of the <a href="https://github.com/rust-lang/cargo/labels?q=regression">regression-</a>
prefixed labels (depending on if it is a regression in an already
released stable release, or it is in nightly).</li>
</ul>
</li>
<li>
<p>Assuming the issue looks valid, switch the <a href="https://github.com/rust-lang/cargo/labels/S-triage">S-triage</a> label for one of the following:</p>
<ul>
<li><a href="https://github.com/rust-lang/cargo/labels/S-needs-team-input">S-needs-team-input</a> — The next steps are not clear, and the Cargo team
needs to discuss whether or not to proceed and what needs to be done to
address the issue.</li>
<li><a href="https://github.com/rust-lang/cargo/labels/S-needs-design">S-needs-design</a> — The resolution of the issue or small feature request
will need more work to come up with the appropriate design.</li>
<li><a href="https://github.com/rust-lang/cargo/labels/S-needs-rfc">S-needs-rfc</a> — This is a large feature request that will require a
public design process.</li>
<li><a href="https://github.com/rust-lang/cargo/labels/S-needs-mentor">S-needs-mentor</a> — This is something the Cargo team wants to address,
but does not currently have the capacity to help with reviewing. <strong>(reserved for Cargo team)</strong></li>
<li><a href="https://github.com/rust-lang/cargo/labels/S-accepted">S-accepted</a> — This is something that clearly needs to be addressed, and
a Cargo team member has volunteered to help review. <strong>(reserved for Cargo team)</strong></li>
</ul>
</li>
</ul>
<p>Anyone is welcome to help with the triaging process. You can help with
reproducing issues, checking for duplicates, gathering more information from
the reporter, assigning labels using <a href="#issue-labels"><code>@rustbot</code> comments</a>, and
creating a test using <a href="tests/writing.html">Cargo’s testsuite</a> (<a href="https://github.com/rust-lang/cargo/issues/11628#issuecomment-1411088951">example</a>).</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="index.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="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="index.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="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 -->
</div>
</body>
</html>