Introduce an issue template

[steveklabnik]

This file is used when opening a new issue.

This is copied from https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports

[rust-highfive]

r? @aturon

(rust_highfive has picked a reviewer for you, use r? to override)

[steveklabnik]

To be clear, I am fairly ambivalent about the idea of templates. But since this feature is now live, I figured that copying our template from CONTRIBUTING.md would kickstart the discussion.

[steveklabnik]

An example of this in action: https://github.com/steveklabnik/testingtesting/blob/master/issue_template.md and https://github.com/steveklabnik/testingtesting/issues/new

[brson]

Many Rust bug reports don't involve code, so making it seem like code is required is weird. Likewise backtraces.

Asking for rustc version is good.

Edit: My opinion is we shouldn't do this, and that the template we've got isn't that great and should probably changed. I like the idea of linking to a bug reporting guide but we already do that; it's hard to notice that link and I suspect not a lot of people click it.

[nagisa]

-1. First and foremost, for a compiler the range of issues is very wide and it is hard to provide a reasonable template. E.g. the backtrace is only applicable to ICEs, version might be useful. Most of the issues aren’t even related to unexpected results.

[shepmaster]

This could be prefaced with a note like:

If you aren't sure how to file a bug, try this template: ...

This might lower the barrier of entry to newcomers (for better or worse). People who "know better" can ignore it and put what they think is appropriate.

[shepmaster]

Most of the issues aren’t even related to unexpected results.

@nagisa This comment interests me. When would you file an issue for something that wasn't unexpected?

[nagisa]

@shepmaster your own issue from the front page #31712 is a feature request for which 99% of the template does not apply.

EDIT: though I agree that “most” might not be the most appropriate word here.

Also I’m against adding this template with the prefix as proposed because it would be a pain to delete it every time :)

[shepmaster]

Many Rust bug reports don't involve code

I'd have to see some examples to know better, but this can be transformed into "steps to reproduce" instead of "code to reproduce".

[shepmaster]

feature request for which 99% of the template does not apply.

I was wondering if someone would mention that. 😇 ... but I think it proves my point.

<Copy the existing text from the issue for the summary>

I tried this code:

let set1: HashSet<u8, FnvHasher> = [1,2,3].collect();
let set2: HashSet<u8, SipHasher> = [2,4,6].collect();
let middle: Vec<u8> = set1.intersect(&set2).collect();
println!("{:?}", middle);

I expected to see this happen: 

The code compiles and `4` is printed.

Instead, this happened:

<copy in the exact compliler error message>

## Meta

<whatever my nightly is>

I think all of us agree about the backtrace though.

[shepmaster]

Note that by giving code to reproduce in my example, I already created 90% of the test that can be added when/if the feature is added. 😈

[nagisa]

@shepmaster note how the issue became 3 times as long compared to the original report, all of which:

1. Has to be read – mostly in full – in order to be understood by the people coming through (triagers, seasoned developers, person interested in fixing it etc);
2. “Forces” you to compose a code sample where none is necessary (instead of just copying the current signature from rustdoc);
3. Includes a bunch of useless information (for that particular issue – rustc version, compiler output, expected output).

I think these three points are enough to prove my point.

[steveklabnik]

Apparently pull_request_template.md exists as well, but that seems even less useful to me, to be honest.

[tyre]

@nagisa

1. Providing more context is very helpful for maintainers. Not everyone who reports bugs is a seasoned developer. The great part of a standardized template is you can skip the parts you don't care about.
2. Having developers walk through how to reproduce is not a negative.
3. Again, depends on the issue. People aren't asking for more process just for the hell of it.

It's an optimization for a particular case: lots of low-quality issues coming in with insufficient context. Is it a pain to "read more"? Maybe a small cost. But nothing compared to the time of having to ask for more context, switch to other work, then come back when the reporter has gotten back to you.

[shepmaster]

I will state upfront that I do not do issue triage for Rust. Anyone that does gets way more of a voice than what I say.

@nagisa we shall agree to disagree, it seems :-)

Has to be read (mostly in full) in order to be understood by the people coming through (triagers, seasoned developers, person interested in fixing it etc);

Yup, and I would hope the added context helps all of those people better understand what is wrong / what the reporter wants.

“Forces” you to compose a code sample where none is necessary (instead of just copying the current signature from rustdoc);

I still believe that this helps with creating a test case as well as providing something that triage can use easily to determine "is this still broken".

Includes a bunch of useless information (for that particular issue – rustc version, compiler output, expected output).

The version gives one point along a timeline. There are likely to be earlier versions and later versions, it's true.

The compiler output contains an error message that other people, not as well-versed with the compiler, might find via a web search.

I grant the "expected output" is less useful here. I probably would have just said "this should compile"

[bstrie]

Ultimately I think Steve does the most triage, so I think it's up to him to decide if this would help improve the quality of reported issues.

Personally, I think a template is a good idea. Having more info in an issue doesn't hurt, especially when it comes to ensuring reproducibility (without which the issue is just an utter waste of time). Having more info in the issue also helps when searching for bugs, since Github's search is so poor otherwise.

[steveklabnik]

I do do a lot of triage. I have complicated feels.

The more stuff that's added here, the less bugs we'll get. Friction means people drop out of processes. Sometimes that's good, sometimes that's bad. I would prefer that more bugs be filed than less.

However, sometimes filing bugs can also be intimidating. We have a pretty steady clip of new people. So a small amount of help here might be better than nothing.

[Manishearth]

Perhaps just filling it with "please see [...] if you need help filing bugs", linking to a section in contributing or something would work? That way, people who are intimidated can just read it. Others can just delete that text and go ahead and file.

[Manishearth]

My main gripe with templates is that most of the time they don't apply, and they can make people feel like they have to word their issue to fit the template (especially newbies), which is unnecessary effort for them and might turn them away.

If we can make it sound very clearly optional, that might work.

[bstrie]

People in here keep saying that "most of the time, templates don't apply", but that's not my experience at all. Having "1) here's what happens, 2) here's what I expect to happen" is the very essence of a bug report.

If you're talking about things like people submitting feature requests, then I contend that that is what the RFCs repo is for.

[steveklabnik]

It seems that at this time, the general consensus is, at best maybe this is useful.

I would rather have more people file "bad" issues and clean them up than add bureaucracy that would discourage issues from being filed.

Thanks for the discussion, all! 👍