How We Write Github Issues
wiredcraft.com
How We Write Github Issues
1–10 of 15 posts
Re: How We Write Github Issues
#2Very interesting points, I mostly follow this kind of rules and use labels as well to improve visual context.
Re: How We Write Github Issues
#3Definitely 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 ;)
Re: How We Write Github Issues
#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 descriptiveness.
Re: How We Write Github Issues
#5Definitely 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.
Re: How We Write Github Issues
#6> 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…
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
#7> 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…
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.
Re: How We Write Github Issues
#8Earlier quoted context omitted.
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.
Re: How We Write Github Issues
#9> 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…
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
#10Good 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?