News for hackers. Stuff that matters.
Re:How We Write Github Issues by beaumartinez on Wednesday January 08, 2014 @08:31AM (#7023320)
> 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.

Re:How We Write Github Issues by skidding on Thursday January 09, 2014 @06:02AM (#7029787)
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

Re:How We Write Github Issues by kibwen on Wednesday January 08, 2014 @01:51PM (#7025585)
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.
Re:How We Write Github Issues by sberder on Wednesday January 08, 2014 @09:29AM (#7023623)
I like short titles with labels in addition to create the context. I find it the best mix for me.
Re:How We Write Github Issues by hunvreus on Wednesday January 08, 2014 @08:33AM (#7023328)
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.
Re:How We Write Github Issues by beaumartinez on Wednesday January 08, 2014 @08:37AM (#7023338)
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.

Re:How We Write Github Issues by dikunlun on Wednesday January 08, 2014 @08:50AM (#7023407)
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.