From 44f70f7620e6414914b1357a51da9fdc03fa6cdf Mon Sep 17 00:00:00 2001 From: Sander Maijers Date: Sat, 23 Apr 2016 14:11:07 +0200 Subject: [PATCH 1/2] docs: add GitHub issue template Adding an [`issue template`](ISSUE_TEMPLATE.md) will encourage that everyone, even a novice, reports issues in the most informative manner. This solution is harder to miss than a section in [`CONTRIBUTING.md`](CONTRIBUTING.md) alone. For experienced Rustaceans, it's easy to disregard/overwrite the template, which is mostly comment, and a good reminder of some points everyone can forget in a hurry. content: word more precisely what information to report --- CONTRIBUTING.md | 25 ++++--------------------- ISSUE_TEMPLATE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 21 deletions(-) create mode 100644 ISSUE_TEMPLATE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d61feef81a80..88858ae3faa82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ contribute, and we appreciate all of them. This document is a bit long, so here' links to the major sections: * [Feature Requests](#feature-requests) -* [Bug Reports](#bug-reports) +* [Issue and Bug Reports](#issue-and-bug-reports) * [The Build System](#the-build-system) * [Pull Requests](#pull-requests) * [Writing Documentation](#writing-documentation) @@ -29,7 +29,7 @@ issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new) rather than this one. New features and other significant language changes must go through the RFC process. -## Bug Reports +## Issue and Bug Reports 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 @@ -46,25 +46,8 @@ extra credit. We won't mind if you accidentally file a duplicate report. Opening an issue is as easy as following [this link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. -Here's a template that you can use to file a bug, though it's not necessary to -use it exactly: - - - - I tried this code: - - - - I expected to see this happen: - - Instead, this happened: - - ## Meta - - `rustc --version --verbose`: - - Backtrace: - +You'll notice we use [an issue template](ISSUE_TEMPLATE.md). It's advisable to +try to follow it, of course depending on the kind of issue you have. All three components are important: what you did, what you expected, what happened instead. Please include the output of `rustc --version --verbose`, which includes important information about what platform you're on, what diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md new file mode 100644 index 0000000000000..78527bc4b1a1a --- /dev/null +++ b/ISSUE_TEMPLATE.md @@ -0,0 +1,45 @@ + + +## Code sample + +`main.rs`: +```rust + +``` + +## Expected behavior + + +## Actual behavior + + +## Meta +`rustc --version --verbose`: +``` + +``` + +## Backtrace + + + From d26993a2cead797f1a50313ece0ec5c6b18a272f Mon Sep 17 00:00:00 2001 From: Sander Maijers Date: Mon, 2 May 2016 20:30:28 +0200 Subject: [PATCH 2/2] simplify issue template, rewrite contrib. guidln. contents: remove overly detailed structure from issue template. contents: clarify what to report about specific types of issues. --- CONTRIBUTING.md | 86 ++++++++++++++++++++++++++++++++++------------- ISSUE_TEMPLATE.md | 42 ++--------------------- 2 files changed, 65 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88858ae3faa82..bf98c8bd72208 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing to Rust Thank you for your interest in contributing to Rust! There are many ways to -contribute, and we appreciate all of them. This document is a bit long, so here's -links to the major sections: +contribute, and we appreciate all of them. This document is a bit long, so +here are links to its major sections: * [Feature Requests](#feature-requests) * [Issue and Bug Reports](#issue-and-bug-reports) @@ -33,33 +33,73 @@ must go through the RFC process. 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. +is a bug or not, feel free to file an issue anyway. -**If you believe reporting your bug publicly represents a security risk to Rust users, -please follow our [instructions for reporting security vulnerabilities](https://www.rust-lang.org/security.html)**. +**If you believe reporting your bug publicly represents a security risk to Rust +users, however, please follow our +[instructions for reporting security vulnerabilities](https://www.rust-lang.org/security.html)**. If you have the chance, before reporting a bug, please [search existing issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93), -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. +as it's possible that someone else has already reported your issue. 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. Opening an issue is as easy as following [this -link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. -You'll notice we use [an issue template](ISSUE_TEMPLATE.md). It's advisable to -try to follow it, of course depending on the kind of issue you have. -All three components are important: what you did, what you expected, what -happened instead. Please include the output of `rustc --version --verbose`, -which includes important information about what platform you're on, what -version of Rust you're using, etc. - -Sometimes, a backtrace is helpful, and so including that is nice. To get -a backtrace, set the `RUST_BACKTRACE` environment variable to a value -other than `0`. The easiest way -to do this is to invoke `rustc` like this: - -```bash -$ RUST_BACKTRACE=1 rustc ... +link](https://github.com/rust-lang/rust/issues/new) and optionally providing +some specific information, depending on the kind of issue you're reporting. + +### Compiler bugs +If `rustc` incorrectly fails compile your code, and especially if compilation +results in an ICE (_internal compiler error_), you may have a compiler bug at +your hands. + +#### Code sample +Please craft a minimal/simple and self-contained code example that (re)produces +the issue. An example is very self-contained if you can run it on +https://play.rust-lang.org/. + + +#### Expected behavior +Please concisely explain what you expected instead of encountering of the issue. +Check if it's helpful to refer to some relevant externalities. +* Did/does the issue not occur with past/other versions? +* Are there very similar (perhaps informal) issue reports outside this issue + tracker? + +#### Actual behavior +Please paste here any human readable output in full. Important information can +be in the initial details, so please don't cut. + +#### Meta +Please include the output of `rustc --version --verbose`, which includes +important information about what platform you're on, what version of Rust you're +using, etc. + + + +#### Backtrace +When compilation has completed but your executable exhibits unexpected errors in +the form of panics, a backtrace is helpful. To produce a backtrace, reproduce +the issue with your compiled minimal example code like so: + +On Windows, issue in PowerShell: +```powershell +$env:RUST_BACKTRACE=1; &".\problematic_executable.exe" +``` +On other platforms, issue in your `sh` shell: +```sh +env RUST_BACKTRACE=1 ./problematic_executable ``` ## The Build System diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index 78527bc4b1a1a..721146a0c2a53 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -1,45 +1,7 @@ -## Code sample - -`main.rs`: -```rust - -``` - -## Expected behavior - - -## Actual behavior - - -## Meta -`rustc --version --verbose`: -``` - -``` - -## Backtrace - - -