How We Write Github Issues

[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.

[skidding]

Couldn't agree more. Within a max num of characters previously established, a title shouldn't be minimal, but say as many things as possible, if they are explicit and clear.

> People's attention is hard to capture, even your colleagues.

True, that's why communicating as much as possible from the title is important, because you don't always expect them to click and "zoom in"

---

Github issues are also essential where I work. We're trying to make them BDD stories, emphasizing most on the customer need and the WHY, followed by what (deliverables) and how (solution)

We went the extra step to have a template that we apply before starting any new issue. I even wrote a Chrome extension a while back, that reads that issue template from an open source repo and applies it in the textarea when you open the /issues/new page on Github. https://github.com/skidding/github-issue-template

[kibwen]

Came here to echo this sentiment. I find that Github's issue search is so painful that long and overly-descriptive titles are essential for finding anything relevant, especially in a project that uses issues extensively.

[sberder]

I like short titles with labels in addition to create the context. I find it the best mix for me.

[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.

[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

[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...

I also followed this up a bit by solidifying our CONTRIBUTING doc: https://github.com/BroadleafCommerce/BroadleafCommerce/blob/...

[sberder]

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