Hacker News Reader

Comment by Lukasa | Hacker News Reader

Yeah, so this is an interesting feature because in my experience it doesn't work.

[We added one](https://github.com/kennethreitz/requests/blob/master/CONTRIB...) for the Requests module a little while ago because we kept getting bug reports that contained incomplete tracebacks or vague problem statements, or questions that were better suited to Stack Overflow.

However, we still get plenty of issues opened that suggest that the user hasn't read the CONTRIBUTING.md. We still get questions on the tracker, we still get people not telling us what version they're using or what platform they're running on.

What I want to know is: is this our fault? Is our text bad? Or does GitHub's UI not accentuate the need to read this document firmly enough?

View on HN

People don't read. That's pretty much it. Maybe, maybe, if there was some in-line text above the issue form submission, and it was very short (like one or two sentences), people would read that. But any long-form prose is going to be skipped, and likely something that requires clicking a link to read an external CONTRIBUTING document isn't going to be read either.

I ran into this a lot in pre-GitHub (and pre-git) days when maintaining OSS. It got to the point where I would reply to emails with a simple one liner "Addressed here: [link]" or, "Bug report requirements: [link]". I felt horribly rude doing so sometimes, but I realized that people were not respecting my time by failing to take a minute or two to read through the bug report guidelines, and so I wasn't going to waste my time being polite. There's unfortunately a lot of entitlement among open source users, and it gets tiring after a while.

Yeah contributing.md doesn't get read much, or it gets skimmed over.

Issue templates seem to MOSTLY fix the problem, so we wrote a bot that sticks in some canned questions when it looks like your bug didn't follow the template. People recoiled to the bot for months but new users were totally fine with it.

I really wish GitHub had some sort of optional facility for a stock template for the "bug" field, as it would save collective years of people's combined lives. It would just need to populate some text in the issue box by default. Call this ISSUE_TEMPLATE.md if you want, etc.

Various third party attempts to do this - like use this bug page instead of github's new issue form, don't really work as the one NICE thing about github is that everyone knows how every project sort of works. Sort of. Which is also the one nice thing as they don't join the lists or really understand how various projects really really work :)

Reply on news.ycombinator.com