It might be useful to have an [`ISSUE_TEMPLATE`][0] file that people fill out when submitting new Github Issues. Although it adds a slight [PITA][1] when submitting bug reports, it should help to avoid the common back-and-forth at the start of most issues to request useful information.
I have written [one such template][2]. The "Prerequisites" section is based on the most common missing/wrong things I've seen in submitted issues. Perhaps it belongs in a `CONTRIBUTING` file instead, but putting it inline in the [`ISSUE_TEMPLATE`][0] makes sure people have to explicitly ignore it.
For now don't worry about spelling or grammar mistakes, but I'm interested to see whether this is wanted at all, and whether any sections or items should be added or removed. We can get the exact spelling and wording fine-tuned when I make an actual pull request.
Feel free to [try it out][3] on my testing repository.
[0]: https://help.github.com/articles/about-issue-and-pull-request-templates/ [1]: http://onlineslangdictionary.com/meaning-definition-of/pita [2]: https://github.com/codebrainz/geany-issue-template [3]: https://github.com/codebrainz/geany-issue-template/issues/new
The idea of having a template to try to get the basic info needed to help is good.
But my first reaction to getting something the size of the example would be "what have this projects devs been smoking?", then I would call them [expletive deleted] and either deliberately ignore the template or just not report stuff. Something that size is self defeating.
Eleven prerequisites with seven references!!! BEFORE we get to any information. Thats totally not something that should be in the template, but sure put it in contributing or other place it will never be read.
I would have only:
1. the geany and GTK version and platform stuff first, thats essential, and 2. whats the problem, and steps to repeat, or 3. whats the improvement suggested, whats the benefit, and exactly how should it work, and "PRs welcome"
Sure there are other things we could ask, as @codebrainz did, but the law of diminishing returns and applicability applies.
I suspect a :bike: :house: may occur here :grin:
I'm not sure whether the prerequisites are better in the ISSUE_TEMPLATE (after all, people only have to skim them and delete the whole section) or the CONTRIBUTING file (which nobody will read), but they are mostly based on things which more often than not result in the first few comments dragging this information out of the submitters.
Just to give random recent examples of something that seems too in-the-weeds for this template, issues related to Scintilla syntax highlighting (number six in my prerequisites) "whether any syntax-highlighting issue would be more appropriate to open with the Scintilla project":
https://github.com/geany/geany/issues/2038#issuecomment-451692721 https://github.com/geany/geany/issues/2029#issuecomment-450795082 https://github.com/geany/geany/issues/2026#issuecomment-450073900 https://github.com/geany/geany/issues/1984#issuecomment-432456351 https://github.com/geany/geany/issues/1981#issuecomment-431623933 https://github.com/geany/geany/issues/1947#issuecomment-419243871 https://github.com/geany/geany/issues/1944#issuecomment-418275247 https://github.com/geany/geany/issues/1889#issuecomment-401271520 https://github.com/geany/geany/issues/1853#issuecomment-386450451 https://github.com/geany/geany/issues/1844#issuecomment-384207408 https://github.com/geany/geany/issues/1827#issuecomment-381764051 https://github.com/geany/geany/issues/1754#issuecomment-362460349 https://github.com/geany/geany/issues/1728#issuecomment-353753512 https://github.com/geany/geany/issues/1714#issuecomment-415222033 https://github.com/geany/geany/issues/1679#issuecomment-342680888 ... too many more to bother finding ...
I can find dozens or hundreds of examples like this of the things I put in the Prerequisite section which are almost always left out of the original reports and require someone to explicitly ask. Moreover, anyone submitting a new Issue only has to read them once and then just delete them before clicking submit, or explicitly ignore them and submit the report anyway.
In any case, I don't mind moving them to a separate `CONTRIBUTING` file, even if they are far less effective.
I don't know if everyone knows about this, but you can dump some of those files you mentioned into a `dot github` directory to keep them out of the repo root. I think .travis.yml might be able to go there too, depending on your prefs.
https://github.com/Homebrew/brew/tree/master/.github
Multiple issue templates are supported as well:
https://github.com/tutao/tutanota/tree/master/.github/ISSUE_TEMPLATE
In effect, when a user clicks "new issue", they are presented with 3 different options.
don't know if everyone knows about this, but you can dump some of those files you mentioned into a dot github directory to keep them out of the repo root.
Yeah, in my example I used a "docs" directory supported by Github since Geany already has that, and there's already miscellaneous documents in there.
Multiple issue templates are supported as well
That's cool! We could probably have at least two for "bugs" and "feature requests" or whatever. I'll have to try it out sometime.
Closed in favour of #2162
Closed #2063.
github-comments@lists.geany.org