Introduce issue templates #6147
Conversation
These are GitHub's default "Bug report" and "Feature request" template. We can modify them as we deem appropriate.
|
r? @matklad (rust_highfive has picked a reviewer for you, use r? to override) |
There was a problem hiding this comment.
Thanks for this! Looking at this again I'm sort of faced again though with conflicts about how much this'll help us. I've never really enjoyed filling out templates myself on other projects in that my bug/feature request never really fits in and it doesn't seem to assist the resolution of the issue in the long run.
Can you describe again the thinking behind adding these? E.g. what's the main expected benefit for us?
.github/ISSUE_TEMPLATE/bug_report.md
Outdated
| - OS: | ||
| - Rust Version: | ||
| - Cargo Version: | ||
| - Release Channel: |
There was a problem hiding this comment.
This is info which ideally we've have a single-shot command to automatically fill this rather than asking the user to explicitly write this in. It may mean that we need to update cargo version --verbose perhaps, or maybe even add cargo report-bug to print this sort of information.
There was a problem hiding this comment.
Either sound good to me.
| A clear and concise description of what you want to happen. | ||
|
|
||
| **Describe alternatives you've considered** | ||
| A clear and concise description of any alternative solutions or features you've considered. |
There was a problem hiding this comment.
One aspect of templates I've always been wary of is that it scares off issues that otherwise wouldn't be created. For example I've stopped filing a bug halfway through sometimes when the issue has seemingly a lot of fields that require a good deal of effort to fill in. For Cargo I'd personally prefer that we sift through low-quality reports than get no reports as there's always a chance that we can spot an actually issue from an ill-reported bug.
In that sense I feel that this sort of section (and maybe additional context?) goes into a bit too much information for a feature request. I'm curious what others think though?
| --- | ||
|
|
||
| **Is your feature request related to a problem? Please describe.** | ||
| A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] |
There was a problem hiding this comment.
This is an interesting framing that we may want to change, having the first example of a feature request being "I'm always frustated when ..." doesn't necessarily set a great tone for bug reports. I know it drains a lot out of me at least reading issues that are just frustrated rants.
| A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] | ||
|
|
||
| **Describe the solution you'd like** | ||
| A clear and concise description of what you want to happen. |
There was a problem hiding this comment.
The "clear and concise" bit here can be removed and perhaps changed to mention that this section is optional, I'd imagine it's fine to report an issue which you're not entirely clear how it'll be solved yet.
There was a problem hiding this comment.
We can vary the wording, of course. But the value here, in my opinion, is accurately capturing as two distinct entities what the problem is, in of itself, vs what the author believes the solution is. Often these two are confused and/or transposed..
So, first off, from https://blog.github.com/2018-05-02-issue-template-improvements/ it looks like this setup will give you the option to use one of these templates, but also the option to "Open a regular issue", so opt-ing out is kind of a visibly accepted option. But going back, the motivation behind this was a conversation about the state of the issue tracker and good quality issues in the backlog, and I proposed trying out GitHub's new issue template, now with multiple template support too. The thinking (or at least my take on it) is that if you guide issue authors into nicely capturing the requested feature or the reported bug, along with the status quo at the time, on average you end up with a better quality issue backlog. In particular (as mentioned above) guiding ticket authors to distinguish their proposed solution (for a feature/bug/enhancement) from the underlying problem they're attempting to solve, has great value. |
|
I think I'm sort of torn on this. I agree that with a template we're likely to increase the quality of bug reports. That being said though I feel that the increase in quality isn't really significant enough for maintainers of Cargo. Put another way, those already familiar with Cargo are unlikely to benefit from the issue templates (I think). In that light, the slight net negative of maybe some reports are lost seems like it would lead to us not wanting to do this. Maintainers aren't the only users of issues though! If we have a large "triage community" or set of folks who aren't so intimately familiar with Cargo then having higher quality issues could in theory have a significant impact on them. I don't think we have much of a set of folks here (no, not you @dwijnand, you know enough of Cargo's internals now you're maintainer level :P), but would could definitely use folks like that! I suppose like many other features we could try this out and see how it goes? In doing so though perhaps we could do so a little more conservatively, perhaps only having feature requests and bug reports, and small (maybe commented out by default) blurbs about each issue. Emoji in the template by default could also be useful to visually distinguish the two as well I think? |
Adapt to feedback comments, and steal (heavily) from the templates in rust-clique/human-panic.
|
Some adaptation pushed (I only had limited time today to think about it much), and also added this to the meeting agenda to discuss. 🙂 |
|
I'll try to respond in more depth later, but overall, I think the idea of issue templates is a good idea (e.g. asking for version information and steps to reproduce), but I feel like the default templates don't fit very well for us and are a bit too structured. |
GitHub does a prompt thing on the right based on issue description, so perhaps that's good enough. This way we avoid sounding too aggressive.
.github/ISSUE_TEMPLATE/bug_report.md
Outdated
| Thanks for filing a 🐛 bug report 😄! | ||
| --> | ||
|
|
||
| <!-- Provide a general summary of the issue in the title above --> |
There was a problem hiding this comment.
I think that can be removed. I think most people know what the title is for.
.github/ISSUE_TEMPLATE/bug_report.md
Outdated
| 2. | ||
| 3. | ||
|
|
||
| **Problem** |
There was a problem hiding this comment.
I would put "Problem" before "Steps".
|
|
||
| <!-- Provide a general summary of the issue in the title above --> | ||
|
|
||
| **Describe the 🙋 feature request** |
There was a problem hiding this comment.
These two sections sound quite similar to me. Perhaps this section could be titled "Describe the problem you are trying to solve". Maybe "problem" isn't the right word, but generally steer the reporter to explaining why they want the --do-awesome-things flag.
|
WDYT @joshtriplett? |
|
The new versions look reasonable to me! As a very minor nit, I'd like to see a bit more consistency between multi-line comments and multiple single-line comments for explanatory text. |
|
Will that do? (I wasn't 100% sure what you meant exactly) |
|
Looks good to me! |
|
@bors: r=JoshTriplett |
|
📌 Commit f53b2f5 has been approved by |
Introduce issue templates I took GitHub's default "Bug report" and "Feature request" templates and modified them a bit to make them work with Cargo. Happy to iterate more. WDYT?
|
☀️ Test successful - status-appveyor, status-travis |
I took GitHub's default "Bug report" and "Feature request" templates and modified them a bit to make them work with Cargo. Happy to iterate more. WDYT?