How We Write Github Issues | Hacker News Reader

How We Write Github Issues

wiredcraft.com

31 pointsdikunlun14 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.

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.

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.

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.

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

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.

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

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 ;)

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.

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)

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

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?

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

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

Reply on news.ycombinator.com