

How We Write Github Issues - dikunlun
http://wiredcraft.com/posts/2014/01/08/how-we-write-our-github-issues.html

======
beaumartinez
> _A bad issue: too much in the title._

"Fixing the performances after the rollout of the last Express.js" is _much_
more descriptive than "performance tool in development environment".

Descriptiveness counts—scanning through a list of issues I'd know immediately
what the first one entails. I wouldn't with the second.

> _Keep titles short and descriptive._

Yes to descriptive, no to short if you're compromising on descriptiveness.

~~~
hunvreus
That'd depend of the context. If you have a lot of issues related to
Express/performance, then maybe being slightly more verbose is the way to go.

~~~
beaumartinez
Say you revisit that issue in three month's time. Would you know what the
cause of the "performance tool in development environment" issue was? Probably
not. "Fixing the performances after the rollout of the last Express.js" tells
you straight away though.

Admittedly it's a minor issue, but overzealously enforcing "keep titles short"
will make titles less descriptive.

~~~
dikunlun
It is a good point. However by keeping most of the issues in a milestone and
making sure those issues are based on actual deliveries help to keep things in
context without a need of a fully verbatim title. This will be the subject of
another post.

------
julianlam
Definitely good advice, but bad issues will always be present, no matter how
many articles are written about it. I fully expect in 10 years to still have
to deal with people pasting entire stack traces in github titles ;)

~~~
hunvreus
I think it's a matter of peer pressure. You can't necessarily guarantee this
on a OSS project, but between colleagues you should be able to set
expectations; "I'm taking the time to properly explain what I'm working on,
and so should you. Especially if you want me to help".

Doing so is also drastically reducing the amount of misunderstandings and the
length of your Scrum meetings.

------
ianbicking
Does "/cc @johndoe" do something that I'm missing? (The "/cc" part is
irrelevant of course, but specifically tagging someone.) I have yet to figure
out what it accomplishes in terms of notifications or queries, seemingly very
little. But for all I know there might be something I'm missing, or a setting
that could be adjusted?

(Edit: maybe it seems superfluous because I typically want notifications for
everything in the repositories that I have greatest interest in)

~~~
hunvreus
You get notified, depending on your settings. It basically subscribes you to
the issue: [https://github.com/blog/821](https://github.com/blog/821)

------
bbsss
Good article, I really agree on an issue being like a log that you can see the
thoughts develop over time. Invaluable for getting people up to speed that are
new to an issue.

What's your take on using labels?

~~~
phillipuniverse
This is how we do it at Broadleaf. We use a combination of milestones and
labels: [http://www.broadleafcommerce.com/blog/broadleaf-issues-
power...](http://www.broadleafcommerce.com/blog/broadleaf-issues-powered-by-
github)

I also followed this up a bit by solidifying our CONTRIBUTING doc:
[https://github.com/BroadleafCommerce/BroadleafCommerce/blob/...](https://github.com/BroadleafCommerce/BroadleafCommerce/blob/master/CONTRIBUTING.md)

------
sberder
Very interesting points, I mostly follow this kind of rules and use labels as
well to improve visual context.

