
Issue and Pull Request templates - joshmanders
https://github.com/blog/2111-issue-and-pull-request-templates
======
jamesRaybould
There is already a way of doing this using the URL like:
[https://github.com/jamesRaybould/go-
mssqldb/issues/new?body=...](https://github.com/jamesRaybould/go-
mssqldb/issues/new?body=%23%23%23%20Story%20%2F%20Task%0A%0A%23%23%23%20Value%0A%0A%23%23%23%20Acceptance%20Criteria%0A%20-%20%5B%20%5D%20%0A%0A%23%23%23%20Notes)

You can then add it as a simple href to the readme.md.

It also means that you can have multiple templates depending on what a user
wants to do, just by having multiple links and changing the content of the
`body` parameter.

Simplest way to get going on this is to use
[http://urldecode.org](http://urldecode.org) to write the markdown you want
and then hit the encode button, take the result and add it after `body=`

We also use it to auto-assign labels using `labels=` in the URL

~~~
anonicode
Do you get many issues that don't use your template because people go to
/issues and click the new issue button? When I create an issue with a project,
I typically don't a link in readme.md.

~~~
0942v8653
You could combine it with the new feature and put a warning message into the
default box saying to click one of the links in the README in order to get an
issue through.

~~~
tehbeard
That is just... Why? That's such a UX failure I'm not entirely convinced you
wreent being sarcastic.

------
jakozaur
Great job!

Next item, be able to star issues.

That would help a lot and we are able to avoid +1 comments.

~~~
michaelmior
Seems like this one is solved by showing the number of subscribers to an
issue. I don't think this really needs to be a separate feature.

~~~
gknoy
I think it makes sense to have a difference in meaning between "I want to be
e-mailed updates about this" (subscribe) versus "I think this is
important/valuable/necessary" (star/vote).

~~~
matthewowen
Devils advocate: if you think it is important, then why don't you want to know
when it's fixed?

Starring instead of subscribing is basically the issues equivalent of "Hire,
but not for this team". If you limit it to people who care enough to
subscribe, you only get the people who actually are invested in it, and avoid
the people who _think_ it should be fixed but who don't actually need it to
be.

~~~
alpb

        > why don't you want to know when it's fixed?
    

Knowing when it is fixed/closed is very much different than getting emails
about every single comment going on about that issue.

Starring issues (as in Google Code Project Hosting) meant "I want to see this
getting fixed" and subscribing issues on GitHub does not show anything like
that. If I am not mistaken, you only see a list of people “participating” to
an issue, you don’t get to see list of people getting emails about that issue.

~~~
morninj
Agreed. Would be great to get an alert only when the issue is closed. That
could also work as a rough voting system.

------
erikb
Now I actually start to worry. Did anybody here ever have the problem of
making people happy with a software project?

The usual complain goes like this "You need to do X because I want to be able
to do Y." In the complainers mind there is the untested idea that having X
will enable him to do Y which solves his unspoken problem Z that he isn't even
aware off. The thing is, at this time you don't know Z. You don't know if Y is
really solving Z. And you don't know if X is really solving Y. And neither
does he. But if you want him to use your tools he doesn't need to worry about
that as much as you.

What happens if you just go like "Okay, user wants X, here is X!" is that the
users will continue to complain (maybe even more) because Z is still not
solved, and because there was no testing and planning involved X is actually
creating another problem Z2 that nobody had before. At least that's my
experience with an open source project I managed for about 3 years.

What I found actually needs to happen is to discover Z and to discover a way
to solve it in the context of the project (which other people may not be as
aware of as you are), and with an at least minimized chance of creating more
problems. Then this actual solution needs to be sold to the users, because
they are not aware of Z, so they think they don't care that you solved Z. But
only after doing all that people will stop complaining (not even remembering
that there was a problem and how much pain you went through to solve it of
course).

Hope that makes sense and explains why I start to worry now, when everybody
starts cheering. What I hoped would happen is that you don't hear much about
the suggested changes, some other changes happen a few weeks down the road,
and then the complains stops without anybody noticing. A success would be that
you don't read about github anymore after 1-2 months. People cheering and
github saying "Hey we did X" is a really bad thing.

~~~
james-skemp
I'm confused, probably because of too much variable usage in your comment.

If one or more of the variables were GitHub, or issue templates, then:

Don't be concerned. The user community listed grievances with some missing
functionality. GitHub listened and implemented some. In this case without
changing functionality for people who didn't want this. (So the person who
likes the URL method can stick with that.)

Good on GitHub implementing something to help their users. Isn't that what we
want? Or do you want then to ignore their community?

~~~
erikb
They implemented the wrong thing though. And now you ask "What's the right
thing?" to which I will say "Nobody knows yet"

X = proposed solution by users, Y = guessed problem by users, Z = actual
problem nobody knows about yet.

The proposed solution is only maybe a solution to the proposed problem,
probably not. Because users won't go and try things out and then come to you
and tell you what they found out. They have a feeling in their stomach and
they tell you about it. The same goes for the problem they tell you about.
It's maybe not their real problem but a symptom of another problem. You need
to go and solve the actual problem.

Example: Patient (=user) goes to doctor (=github) and says "I have a headache
(=Y), please give me some pills against headaches (=X)". Well, headaches can
be because of lack of sleep, lack of water, too many worries, an infection, or
maybe even cancer. Now the doctor's job is to figure out which of the actual
problems it is. He talks to the user, does some analysis and figures out the
actual problem is lack of water (=Z!!!). He tells the patient to drink more
water (solving Z, Y is indirectly solved, and no word about X). Patient goes
home, drinks more, is happy, doesn't come back to the doctor.

------
VeejayRampay
Well done Github. Simple and elegant solution that I hope will help people a
lot.

------
swang
Kinda meh on adding it to the repo since it's yet another file I have to
"manage" that isn't really part of the working code.

~~~
aidenn0
Would you seriously rather have it unversioned and untracked and managed with
some random webpage on github?

~~~
makecheck
Something only belongs in the same branch as the code if it should be forever
tied to the same version as the other files in that branch.

Suppose I check out a project using a version from a year ago. Project
maintainers would certainly not expect me to use last year’s issue template,
last year’s preferred pull request layout and last year’s rules for
contributing! That is why shoving things into the "git" repository is a hack.

Having this stuff under _some_ revision control is useful but it could be a
separate, parallel repository. Frankly, I think everything for project
management should be in one repository, and everything for code and
documentation should be in another, and GitHub should be able to use files
from both to present a project site.

~~~
BHSPitMonkey
GitHub is always going to use the issue template that's on master, not the
template from whichever version you happen to have checked out on your
machine.

~~~
joshmanders
Current file on master to boot. But what makecheck is saying is that only
what's in current master matters, not what's in `feature/something-here` or in
a commit tree from last year. So shoving it in the repo isn't really a good
solution.

~~~
dwightgunning
Having the templates in the repo at least gives you a degree of portability.

I'm guessing there isn't an "export issues" feature so the above point is
moot.

I favour the portability.

~~~
jrochkind1
Sure you can export issues from Github, easily.

[https://api.github.com/repos/rails/rails/issues](https://api.github.com/repos/rails/rails/issues)

------
anonicode
> This is the first of many improvements to Issues and Pull Requests that
> we're working on based on feedback from the community

So there is more to come

~~~
secstate
Geez. I would hope so. Too bad it took them the better part of half a decade
to listen to users. I've already moved a number of my personal projects to
Gitlab, Bitbucket or a self-hosted Gogs installation.

I've still got reasons to stick with Github for some projects, but it's not
the new hotness it used to be.

$10 says the next new feature is voting on issues.

~~~
jaywunder
If the next feature is voting on issues then that would be great. They'd be
implement Ling the features people are asking for.

~~~
anonicode
GitHub had issue voting years ago and got rid of it because people hated it.

------
minimaxir
The template is more for actual issues with the software than to-do lists/user
grievances, the latter of which I see used more frequently in GitHub Issues.
Maybe it's time to separate GitHub Issues into Issues and Discussion.

EDIT: Missed the fact that the feature is opt-in by the repo owner, which
makes things more expected depending on the nature of the repo. Although now
thinking about it, the separation is still not a bad idea.

~~~
dimgl
I don't agree. I think this is a great step into encouraging users to follow a
format when submitting issues. It would make it easier to add tags to these
issues as well. Any other discussion can be submitted the same way, you'd just
remove the template and start typing.

~~~
joshmanders
Indeed. Triaging issues which is a huge issue can now be simplified heavily
with the usage of a bot that parses the template and tags issues.

This is a great step forward and I'm excited that GitHub is doing this.

------
_ikke_
github released an announcement: [https://github.com/blog/2111-issue-and-pull-
request-template...](https://github.com/blog/2111-issue-and-pull-request-
templates)

~~~
Rican7
... that's what the HN link is

~~~
mintplant
The original link was to [https://github.com/dear-github/dear-
github/issues/125](https://github.com/dear-github/dear-github/issues/125)

The link was changed to the GitHub blog post sometime in the past hour since
_ikke_ commented.

~~~
skeoh
Is there a way to check what was linked originally or do you just have to
click the link before it's changed to know?

~~~
detaro
dang normally comments when he changes a link, as he did here:
[https://news.ycombinator.com/item?id=11120948](https://news.ycombinator.com/item?id=11120948)

~~~
skeoh
Ah, cheers. Didn't notice that.

------
steveklabnik
I have a PR open for Rust to use this. I and others are very skeptical in
general, but there's some interesting discussion so far:
[https://github.com/rust-lang/rust/pull/31732](https://github.com/rust-
lang/rust/pull/31732)

------
lr
I asked Craigslist to do this years ago for the "for sale" sections, so that
people included the number of doors on a car, the color, etc., and the kind of
heat in an apartment, and so on. Such a simple thing, and would make searching
so much better, and the service in general better.

~~~
BHSPitMonkey
Craigslist has dedicated form fields for a lot of those things, which can then
be used with search filters. The problem is that they aren't mandatory, and
most users don't fill them in.

The side effect of this is that if you use the search filters, you risk
missing out on a result which matches your criteria but lacks the metadata.
(Craigslist doesn't have an option to search for only Blue AND Unspecified, so
there's no good way to just hide the explicitly non-Blue cars.)

~~~
mwhite
Allowing sellers not to fill out additional information that they easily could
provides a useful signal to buyers about how well the transaction is likely to
go.

------
colinodell
pull_request_template.md also works.

~~~
captn3m0
>Issue template filenames are not case sensitive, and can have an extension
such as .md or .txt.

~~~
anonicode
colinodell posted that before the blog announcement when we only knew about
issue_template.md. It was to point out that you can do this with pull requests
as well, not that it was case insensitive.

------
tobr
So, the issue template is just a default text that individual users can
modify, delete, or otherwise disregard?

~~~
andrewguenther
Would you also like for it to ensure that all check boxes in your template are
checked prior to submitting? Ask the user to please submit to a lie detector
test? I think this is a completely reasonable solution to the problem and will
cover the 99% case.

~~~
tobr
I'm not sure why you think I'd want that.

I do however feel like it's a temporary and half-hearted quick fix. If it were
possible to add custom fields to the issue tracker, they could be used to sort
and filter issues. They wouldn't have to be required, but maybe if you don't
fill them in, your issue would be labeled "incomplete".

Since they're now asking people to go ahead and add a template file to their
repos, it will make it more inconvenient to change this later.

------
fiatjaf
I want to know how this works: [http://gitmagic.io/](http://gitmagic.io/)

~~~
gitmagic
Send us an email at hello@gitmagic.io and we will try to answer your questions
:)

------
marcinkuzminski
How does that work with branches ? Is there a master branch required to have
this file, what if project doesn't have master branch ?

I think the concept of having a file in source code is flowed for DVCS unless
you have so called "source" branch that you can define that is a default
source of such information.

~~~
JeanSebTr
You can set the default branch [1] which will be shown on your repo's page and
used by default for pull request.. I guess it should take the templates from
that branch

[1] [https://help.github.com/articles/setting-the-default-
branch/](https://help.github.com/articles/setting-the-default-branch/)

------
arnarbi
Why isn't this in a separate branch akin to gh-pages, or a separate repository
akin to the wiki data?

~~~
jrowley
I think a hidden folder is a decent compromise.

>If you're worried about the added clutter in the root directory of your
project, we also added support for a .github/ folder. You can put
CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in
.github/ and everything will work as expected.

~~~
1qaz2wsx3edc
I think the `_TEMPLATE` is unnecessary and the `.github` folder a good
compromise. However I'll take github listening to the community regardless. +1

------
logn
The problem I have with this is, I don't want a template for the comment a
contributor leaves on a PR; I want to display a message to them before they
submit a PR. It's not a standard way to display messages, requiring users to
read editable text (that has no clickable URLs) and then delete that text
after they read it and submit.

~~~
skeoh
Does CONTRIBUTING.md fulfil this requirement?

~~~
logn
Thanks. Wasn't aware of that. Mostly fulfills the requirement.

------
kuschku
It’d be interesting if it’d provide a separate input box for each section of
the template – maybe even a graphical editor for lists if the template
specifies a list.

------
atrotors
Well, it seems like the open letter is working!

I hope they address the other issues as fast as this one. Rating system is the
next one on my list.

------
rurban
I'm excited, but the PULL_REQUEST_TEMPLATE.md name is too long for root. What
about PULL_REQUESTS.md and REPORT_ISSUES.md?

~~~
sjrd
The article says:

> If you're worried about the added clutter in the root directory of your
> project, we also added support for a .github/ folder. You can put
> CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in
> .github/ and everything will work as expected.

So you can put them in `.github/` if you don't want them in root.

~~~
rurban
I read this, yes. In .github/ people will not see it, and is even more
worrysome. It belongs to root, same as CONTRIBUTING.md

~~~
geofft
What's the use case of people seeing it? GitHub should be adding it
automatically; issue reporters aren't copying-and-pasting the template
manually. The only people who should really need to see the file itself are
maintainers (or fork maintainers), unless I'm missing some use case.

------
VeilEm
Doesn't seem to work on enterprise github yet. :(

~~~
gjtorikian
GitHub Enterprise releases typically run a few months behind GitHub.com
changes. You'll likely have to wait until GHE 2.6. Sorry!

------
pducks32
I'd like them to choose a folder name that isn't specific to a site. .github
would look silly on hit lab but I like the idea of having a serrated folder.

~~~
0xffff2
Trying to use a GitHub only feature on GitLab would look equally silly... This
is very much a GitHub specific implementation. It makes sense for it to be
identified as such.

It would be nice if they used a specific branch a la gh-pages so that
everyone's Git repos don't have to be polluted with GitHub specific files.

~~~
slavik81
That's an interesting idea. Having something like a gh-config branch for all
the configuration would keep it isolated.

------
dang
Url changed from [https://github.com/dear-github/dear-
github/issues/125](https://github.com/dear-github/dear-github/issues/125) to
the announcement post.

------
shmerl
What about attachments to issues? Using gist for it is simply annoying.

~~~
andrewguenther
Attachments have been around since 2012:
[https://help.github.com/articles/file-attachments-on-
issues-...](https://help.github.com/articles/file-attachments-on-issues-and-
pull-requests/)

[https://github.com/blog/1347-issue-
attachments](https://github.com/blog/1347-issue-attachments)

~~~
shmerl
Limited to images? Am I supposed to take a screenshot of some huge error dump?
A workaround is to use gists. But it's not a good workflow.

~~~
technoweenie
GitHub also supports txt and other common document formats:
[https://github.com/blog/2061-attach-files-to-
comments](https://github.com/blog/2061-attach-files-to-comments)

~~~
shmerl
Ah, that's a recent addition. Thanks for the pointer. Does it work for bugs?
The post mentions pull request comments.

~~~
anonicode
Yes. It works on issues too.

------
EC1
There's a special place in hell for people that make jokes and post massive
animated memes in issues.

~~~
alextgordon
Heaven must be a real party then.

------
thescribe
This sounds like more 'enterprise' bureaucracy. Coming soon, overly
complicated paperwork.

~~~
badlogic
If you've ever managed a big OSS project you'd not think of it like
'enterprise' bureaucracy but a time safer. If OSS users can't even be asked to
fill out a minimum amount of information based on a template, then I have zero
interest spending my free time helping out.

~~~
acdha
Yes, OSS users have a very wide gamut — for everyone who sends a pull request
with good troubleshooting and a patch, there must be half a dozen people who
click New Issue, submit minimal information and, if you're lucky, come back a
couple of days later and acknowledge that the real problem was a hacked up
local install, using a 5 year old version of a core dependency, etc.

------
gcb0
talk about moving slow.

two years and that's what we get? meanwhile my bigger diffs are still garbage.
and we have to use other companies to have a simple agile board... and don't
even get me started on decent branch management and rebases...

sigh. really hate that my employer buys that

