How We Write Github Issues • Hacker News Board

Re: How We Write Github Issues

#11

Post by ianbicking » Wed, Jan 08, 2014, 4:56 PM UTC

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)

Re: How We Write Github Issues

#12

Post by hunvreus » Wed, Jan 08, 2014, 4:58 PM UTC

ianbicking wrote: post #11

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 t…

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

Re: How We Write Github Issues

#13

Post by phillipuniverse » Wed, Jan 08, 2014, 5:11 PM UTC

bbsss wrote: post #10

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

Re: How We Write Github Issues

#14

Post by kibwen » Wed, Jan 08, 2014, 6:51 PM UTC

beaumartinez wrote: post #4

> 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 descripti…

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

#15

Post by skidding » Thu, Jan 09, 2014, 11:02 AM UTC

beaumartinez wrote: post #4

> 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 descripti…

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