Comment by Permit
10 years ago
This first request is the anti-thesis of GitHub's simple approach:
>Issues are often filed missing crucial information like reproduction steps or version tested. We’d like issues to gain custom fields, along with a mechanism (such as a mandatory issue template, perhaps powered by a newissue.md in root as a likely-simple solution) for ensuring they are filled out in every issue.
Every checkbox, text-field and dropdown you add to a page adds cognitive overhead to the process and GitHub has historically taken a pretty solid stance against this.
From "How GitHub uses GitHub to Build GitHub"[1]: http://i.imgur.com/1yJx8CG.png
There are tools like Jira and Bugzilla for people who prefer this style of issue management. I hope GitHub resists the temptation to add whatever people ask of them.
[1] http://zachholman.com/talk/how-github-uses-github-to-build-g...
> adds cognitive overhead to the process
Yes! The maintainers deliberately want to add cognitive overhead so the quality bar for creating issues is higher.
By having simple zero-friction forms, you haven't removed cognitive overhead. You've simply shifted the cognitive load into the followup messages asking for clarification of "reproduction steps", "version tested". The issues' threads therefore begin with "meta" type questions which duplicate the checkboxes and dropdowns you were trying to avoid.
The default can remain zero-friction but it seems very reasonable to offer options for maintainers to gain some control over their inbox.
So use a real issue tracker. Most of the big ones integrate with github. Why should they reinvent this wheel?
>So use a real issue tracker.
That's a reasonable answer -- but it's an answer to question I wasn't addressing. Whether github reinvents the wheel is not relevant to my point.
I was specifically debunking the illusion that "simplicity of the issues submission form == no cognitive overhead".
If the "issues creation" web form is lightweight, the submitters will eventually expend "cognitive overhead" by clogging up the threads with clarification messages.
If the project maintainer uses your solution of an external tracker, that means the submitter still expends cognitive overhead by noticing that the project's "issue tracking" has been disabled, and then reading front page README.TXT or CONTRIBUTIONS.TXT to figure out what external website he's supposed to use to submit issues. No doubt the web forms[1] on those external trackers will have the checkboxes and dropdowns that some people are suggesting people avoid.
The "cognitive overhead" required to clarify and provide meta-descriptions for bug reports is inescapable. You're only deciding whether it is structured or unstructured and where it is shifted.
Your reply is going in different direction from cognitive overhead and on that perspective, I don't know what makes the most sense. My guess is that many open source maintainers don't need a heavyweight tracker that can do things like assign tasks to multiple programmers, burn down dashboards, correlate activity hours to billing, etc. They don't need all that. They just want a template to improve how users file issues. Maybe a survey would provide insight as to whether your answer is the most sensible.
[1]https://www.google.com/search?q=jira+submit+issue&source=lnm...
If not to be a hosted software lifecycle tool, what the hell is Github even for?
1 reply →
Zero structure just leads to lots of shitty issues that have no information on what version of the software it was against, no reproduction steps, and no stacktrace or debug output. I'm tired of closing issues with "I cant reproduce at all, maybe you're on an old version? Anyway feel free to open a new bug if you ever come up with a reproduction step..."
A simple optional field to include the version number that the issue was being reported against would do wonders for my interaction with users.
And you don't need to include that on your software project, but really if our users can't be bothered to tell us what version they're running, I have many, many other issues to fix which I know are broken in master.
Which I guess is the difference. If you're a small project with few users, then the handful of bug reports you get are useful and you want a zero barrier.
I have literally thousands of bug reports, hundreds of those will be left without ever being fixed (even though they may be perfectly legitimate). I have to triage. If a user is blocked by not being able to tell me what version they are running then that pre-triage of making them not even bother to cut a ticket with bad information is useful because then they don't waste any of my time...
This is very true. While clunky to use most support sites for enterprise software includes these types of fields as mandatory to complete a support ticket.
As someone who has opened issues myself on projects in gitHub its easy to be unaware or even forget all the information a maintainer would need to reproduce the issue. As someone who uses an open source stack every day anything to make the whole issue flow better for maintainers and users I'm for 110%
But the big thing that GitHub doesn't use GitHub for is interacting with the masses.
- GitHub doesn't use GitHub issues to take feature requests or bug reports.
- GitHub doesn't use Pull Requests to allow users to submit bug fixes
When all your issues and pull-request are being raised by a defined set of people who are (or ought to be) committed to the same collective goal (because they're employees of the same company) you can develop a culture and norms around how those things work.
If "Some Guy" at GitHub raises issues where the only description is "This feature doesn't work on Mac" or raises PRs where the only description is "this fixes a bug I found" the cultural pressure would teach him/her that's not how things are done, and if the lesson wasn't learned, then they wouldn't last at GitHub.
When the people you're interacting with are infrequent contributors, it's a different scenario. They need guidance. They need to be pushed to go down the helpful path on their first attempt, because there are too many new contributors and they often don't stick around for long enough to change behaviours by osmosis and cultural pressure.
> Every checkbox, text-field and dropdown you add to a page adds cognitive overhead to the process
I do concur, but there should be at least some of them. One shouldn't have to hope that people will be kind enough to submit proper issues, the platform should force them somehow to do so. I think, if a study of github issues was made, we'd see that about first five messages on a given issue would be those of maintainers craving for more input. What is the output of dmesg, how is your configuration, what is the output of the process, can you run it with the verbose flag on... A bit of cognitive overload is good, so that who submit bugs are those who take the burden of doing so.
If I read it right, they're not asking for a more complicated default for all projects, just that they can customize it for their projects.
And I agree, simple is good... but simple is also bad for large projects, as while it makes it easier to create a ticket, it makes it harder to track for the maintainers. They are (rightfully) looking to ease their work, and I do believe it is a net win for both sides if filing a bug is made a little harder, but it becomes a lot easier to manage.
It can be as simple as a text file that is dropped into the content-free TEXTAREA that currently greets new issue reporters. Try running a big project like jQuery, Angular, or Babel and you'll understand how important a feature like this would be.
Disagreed. In a free-for-all environment like FOSS, collective lack of details means more time wasted to gather/request for relevant information. Maintainers have the rights to request for such things before sifting through a potential mess of mostly incomplete issues/PRs. Their time is better spent anywhere but gathering correct versions to chase down a bug. People should have the common sense to provide those beforehand but alas, many do not.
It may take cognitive overhead away from the submitter but it shoves it onto the maintainet at the same time. Instead of 100 people having to deal with 1u of cognitive overhead each, you have 1 person having to deal with 100u or more to extract information from the submitters.
This is why your application should always have a "dump version string"-button, conveniently embedded together with your "report bug" button which doesn't have to be more advanced than simply opening your email-client or forward you to a webpage. This form should be free text but pre-filled with the version string pasted at the top and contain headers that invite the user to fill in the rest, such as Reproducing: <write what you did to cause the bug>. 100 different drop-downs makes nobody happy.