How We Write Github Issues

How We Write Github Issues(wiredcraft.com)

31 points by dikunlun 12 years ago | 14 comments

> 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 12 years ago | |

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 12 years ago | |

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 12 years ago | |

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

hunvreus 12 years ago | |

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 12 years ago | | |

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.

julianlam 12 years ago |

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 12 years ago | |

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 12 years ago |

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 12 years ago | |

You get notified, depending on your settings. It basically subscribes you to the issue: https://github.com/blog/821

bbsss 12 years ago |

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 12 years ago | |

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 12 years ago |

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