docs: add GitHub issue template

[sanmai-NL]

Adding an issue template 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 alone. For experienced Rustaceans, it's easy to disregard/overwrite the template, which is mostly commented out, and a good reminder of some points everyone can forget in a hurry.

Also, word more precisely what information to report

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @aturon (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[sanmai-NL]

r? @steveklabnik

[hanna-kruppe]

Previous attempt: #31732

[steveklabnik]

Yes, we decided collectively to reject this before, and not much has changed since then. So I will give this a close. Thank you though!

[sanmai-NL]

Reading back that thread, I do not recognize how you summarize it @steveklabnik, i.e. that you collectively rejected this. @tyre, @shepmaster, @bstrie were all in favor and gave good motivations for that. You and others were on the fence. Only @nagisa was against, thinking it would force issue filers to do something. Yet is very clear in this template that everything is optional. Why would it be difficult to clear a text box in the uncommon case you're not reporting an issue that is covered by the template? If that's objectionable, what about creating a simplistic generic template (e.g., the rustc verbose output is always useful)?
Please consider that you and other maintainers not just wasting your own time, but also that of issue filers who wouldn't immediately report all relevant information clearly enough? I don't think ‘not having to read or write’ stuff (the only argument against) is worth spending potentially a lot of time over back-and-forth with reporters. This repo is at the staggering number of 2,361 open issues, isn't that a good reason to reconsider your earlier decision?

[steveklabnik]

I will re-open it if you feel that way, and we'll see.

Please consider that you and other maintainers not just wasting your own time, but also that of issue filers who wouldn't immediately report all relevant information clearly enough?

I don't think it's a waste of my time, and I also don't think it's a waste of other people's times. In the end, if we need more info, then we ask for it; this isn't just for new bug filers. Furthermore, not all issues have the same template... so that's tough.

Furthermore, we don't really have a problem with people posting bugs that don't have enough information. It does happen from time to time, but it's not something that happens particularly frequently enough to be an actual problem.

This repo is at the staggering number of 2,361 open issues, isn't that a good reason to reconsider your earlier decision?

It's not really that many. We have a lot of stuff going on in this repo, including things like tracking issues, documentation, etc... for a project of this size, it's really not much. Firefox has 22,000 bugs open right now, for example.

[nagisa]

haven't shared it yet

What’s the “it” here?

This also should mention, that the section is optional and only relevant for compiler crashes.

[nagisa]

I guess I’m not as opposed to a template as I was previously (even after having seen something as outrageous as ycm’s one), but I still find the template overly big (it took me a minute to read it all!). I think being more concise and formal would be better.

I like the first paragraph, but the rest of the template then goes on to state the demands instead of providing options. E.g. the code sample template could be like this:

Some code that (re)produces unexpected results, if any. It could be a: small snippet of code, link to a branch/commit of a public project etc. 

[caipre]

If the template is added, I'd prefer it to live in a .github directory. CONTRIBUTING.md could also move there, but that one still feels okay at the root level.

[sanmai-NL]

@steveklabnik:
Your blog post about open source gardening was an interesting read in this context. Sure, you may personally be able to handle issue triage at this scale so far, but this young project is already one of the largest GitHub projects now. A similarly sized GitHub project, Docker Engine, is also using issue templates. I don't think this has caused them problems or frustration. Your initial rejection surprised me since the PR seemed uncontroversial and the rejection wasn't well supported. I had prepared this PR for a future in which this issue tracker will be heavily used by novices with unusual configurations and simpler, common issues instead of mostly experienced compiler hackers and other insiders doing internal discussions.

[sanmai-NL]

@nagisa, @arielb1:
I mostly agree with your comments. I'll revise this PR so that all issue type specific matter will remain in CONTRIBUTING.md. This will address the longishness and overspecificity/low relevance of parts. I'll remove the text requesting reporters to suggest issue labels, indeed we'd better not encumber reporters with this aspect of issue triaging since it wouldn't work that well anyway, I suppose. As for the formality of the text, I think the issue template text reflects the style of the other documentation, e.g. the contributing guidelines. Writing in a more formal style may be the kind of ‘process’ @steveklabnik dislikes, since it may come across as a tad pedantic to novices.

@caipre: I disagree with you there. Though ISSUE_TEMPLATE.md is technically ‘GitHub-specific’, its contents has meaning in its own right: what to write down in case of an issue. Because of that, I prefer the file to be visible/easily found. For example, the issue template could be relevant documentation from local repository clones as well.

[steveklabnik]

@sanmai-NL, I'm not saying that issue templates are bad for every project. And, that blog post wasn't about my personal projects; it was about Rails, one of the largest Ruby projects in existence.

To sort of re-iterate my position here: It's not clear to me what the motivation actually is. We don't have a problem of people filing far too many bugs with bad information. I read every single issue and comment on this issue tracker, and it's not a problem, in my opinion, that we share. Can anyone produce a list of bugs which this template would have fixed, and in enough volume to justify adding a template for them?

Furthermore, we use the issue tracker for so many things that having a template can make filing certain kinds of bugs worse. For example, "these docs could be better" bugs don't really have "steps to reproduce." I'm not sure that we can make a template that fits all of the use cases but also doesn't introduce a bunch of junk that you have to delete based on what kind of bug you're filing.

[sanmai-NL]

@steveklabnik: I didn't say that that blog post is about your personal projects, did I? Do I misunderstand you?

Making a list of suboptimally handled issues would be good indeed, but I'd first like to discuss this PR a bit further. In case you do not believe in it at all anymore, it may be hard to convince me or others to invest time in thoroughly supporting the PR with data. Another thing: early adopters may be better issue reporters. So past data will have limited forecasting representativity.

The tradeoff is essentially this:

A

Present issue reporters an empty issue text box. When they do not have a documentation issue, they go to CONTRIBUTING.md, view the raw file, copy the relevant Markdown, paste it in the issue text box, and then fill out all the details they think relevant. They are not instructed or reminded at all unless they have first (re)read the contributing guidelines.

B

Present issue reporters a generic issue template, mostly in the form of unrendered comments, in the issue text box. Insofar they do not need it, they remove it. Insofar they do, they fill in the details. When completely irrelevant, they e.g. press Ctrl-A Del. They are always reminded to check for existing issues and welcomed to report their issue, since that is in the top few lines.

I think approach A, the current approach, will overall cost issue reporters more time in the long term, and will generally please them less. In my view, based on the responses by others in this thread it's key to keep the issue template minimal, which is a slightly different approach than in the commits at present. The template would then refer to CONTRIBUTING.md for detailed templates for specific issue types. The bunch of junk perception wouldn't be justified then anymore.

[steveklabnik]

Maybe I just misunderstood you. No worries :)

In case you do not believe in it at all anymore, it may be hard to convince me or others to invest time in thoroughly supporting the PR with data

I mean, I'm just active on this thread; maybe other committers believe differently than I do.

[sanmai-NL]

As others have stated in your previous PR (I'm being lazy and not citing them again), your opinion is crucial and I'd say final. Besides formally deciding, you also handle most issues and are in charge of documentation. Your experience is also worth more than my theory and common sense. This is why I'm slightly hesistant to spend much more time and words on this relatively minor PR if there's a fundamentally different perception.

[sanmai-NL]

@nagisa @steveklabnik
(Since you two have been most involved in this issue.)
What about this revised PR?

[steveklabnik]

@sanmai-NL I have been wanting to bring this up at a core team meeting, but we didn't get to it last week. Sorry about the delay here.

[sanmai-NL]

ping @steveklabnik

I've noticed quite a few incomplete compiler bug reports recently. Have been trying to help out there, but merging this PR soon will hopefully address this more effectively.

[steveklabnik]

@aturon was supposed to be leaving a comment; we talked about it at the core team meeting last week.

On May 30, 2016, 14:31 -0400, Sander Maijersnotifications@github.com, wrote:

ping@steveklabnik(https://github.com/steveklabnik)

I've noticed quite a few incomplete compiler bug reports recently. Have been trying to help out there, but merging this PR soon will hopefull address this more effectively.

—
You are receiving this because you were mentioned.
Reply to this email directly,view it on GitHub(#33164 (comment)), ormute the thread(https://github.com/notifications/unsubscribe/AABsiuNuecWvRVP0IstpsKd7fB9cDFMNks5qGy0cgaJpZM4IOLUo).

[aturon]

Hey -- apologies for the very overdue response.

As @steveklabnik says, the core team discussed this in a meeting a few weeks back. I'll try to summarize the key points here:

• Most of us feel like the problems we have with issues have more to do with triage and tracking/action-taking, rather than the quality of the issue itself.
• In particular, issues generally get quick feedback, and low-quality issues are quickly improved.
• Adding the template may make it more intimidating to file an issue, depending on what exactly the template says. (Of course, you could argue that having no template can be intimidating, in a different way).
• Above all, we feel it's more important for people to open issues and otherwise take part in the process than to get things right on the first go -- if an issue is incomplete, that gives us a chance at direct human interaction with a newcomer.

Thus, on the whole, our sense was that a template may well do more harm than good. Of course, it's really hard to know for sure!

@sanmai-NL, you say you've seen a lot of recent examples of issues that would've been improved with a template. It'd be great to collect some of those examples so that we can discuss in more concrete terms.

[sanmai-NL]

@aturon: Just to reaffirm your perspective, have you looked again at the current issue template? It's only a few lines now, far from imposing.

A lot of the guidance is now given in the contribution guidelines. And that part is now plain and uncontroversial improvements, I think.

(Of course, you could argue that having no template can be intimidating, in a different way)

That argument is not far-fetched indeed, IMO. Why would users perceive a nice, helpful, easy to wipe out, optional template as more intimidating than staring into blankness? What about students, very young people, people with limited command of English, etc.?

It's very easy to provide examples of ‘poorly filed’ issues (not dissing anyone). Now, I'm not spending a whole lot of time or going to argue anything subjective, so I'm limiting myself here to a simple audit of whether sufficient versioning info (rustc meta, VCS revisions, dependency context, OS, etc.) is provided in the report (as in, opening post). Working my way down from the current top 13 issues ranked by filing time:

Table 1
rank, issue: description

1. 2, internal compiler error: unexpected panic on dirty fs (arch. mix) #34203: Misses basic versioning info.
2. 5, Suggest use self::Thing::OtherThing when using use Thing::OtherThing #34191: Misses basic versioning info.
3. 6, asmjs test runner should detect Node binary name #34188: Misses basic versioning info.
4. 7, Macro expansion in for trait items #34183: Misses basic versioning info.
5. 8, Paths to source files for inlined items from extern crates not absolute in debuginfo #34179: Misses basic versioning info.
6. 9, MIR too miraculous on ARM? #34177: Misses basic versioning info.
7. 10, doc: Broken link in "No stdlib" Page. #34176: Better, but has non-permalink versioning info.
8. 11, regression: ICE on an unconfigured interpolated item in a macro invocation #34171: Misses basic versioning info. A relatively bad case, since it's a plain ICE.
9. 12 std::ops::Range does not implement std::hash::Hash #34170: Misses basic versioning info.
10. 13, Add expected error code in code blocks flags #34168: Not critical here, but such a discussion should include a short historical note (need not be more than a simple Git revision range) so that later searches will quickly tell up to what version rustdoc from this Rust implementation did not have the functionality up for discussion there.

An ‘error rate’ of 10/13 based on a random sample at one recent moment.
Since you're really seriously pondering this issue/my PR, I suppose it deserves attention what you guys/gals want from the issue tracker. I would suggest that it is an archive of issues, that should be amenable to analysis and should be at least somewhat indexable/searchable. It's not a chat/forum, right? There's also the formal RFC process, but is there then a gap where users wish to address some issues more actively than via the forum, more actionably than via the chat, less formally than via the RFC process?

edit: removed one irrelevant sentence about Rust itself.

[aturon]

@sanmai-NL FWIW, I'm not personally opposed to a template; was just trying to summarize the tradeoffs raised by the core team.

I agree that having more version info would be helpful. In practice, I think what often happens is that one of the core developers attempts to reproduce, and then logs the precise version information of the reproduction. That works reasonably well -- that's basically the first step anyone does to diagnose anyway -- but fails in the case that the bug can't be reproduced and the original filer has disappeared.

As far as I can tell, the currently proposed template wouldn't really address the problems you're pointing out in the sample -- it doesn't talk about version information, for example. Most of the instructions it gives are pretty obvious (e.g., check for an existing issue first, or try to be clear/concise).

[alexcrichton]

Closing due to inactivity, but feel free to resubmit though!