How we use labels on GitHub Issues at Mediocre Laboratories
3The GitHub issue tracker is pretty great. Mostly because of the deep integration with GitHub source control but also because its slim set of features isn't trying to do too much.
GitHub doesn't have a ton of fields to fill out when creating a new issue. Great when you want to add a new issue to the backlog quickly but comes with the tradeoff of requiring a bit more effort when you're finding appropriate things to work on.
By "appropriate" what I really mean is avoiding high effort, low impact work. I can't tell you how often I've seen developers spinning their wheels in the bottom-right section of this graph:
To help us avoid what I've been calling the "bottom-right thankless task wasteland" we've come up with a few conventions around GitHub issue labels. If you've ever managed labels in GitHub before you're probably familiar with their fancy color picker that displays a "solid" color palette over a "muted" color palette.
Here's how we use labels on GitHub Issues at Mediocre Laboratories:
- 3 levels of priority (solid red for high, solid yellow for medium, soild green for low)
- 3 types of issues (muted red for bugs, muted yellow for technical debt, muted green for features)
- Developers can tag an issue with any other label as long as it starts with a ~ character and is set to light gray (#eee)
Notice anything about that list? 3 conventions, 3 priorities, 3 types of issues, 3 colors. 3 is a magic number. I love 3.
You can see an example of how we're using GitHub labels over at some of our open source projects, like Electricity.
Oh, you might be wondering... why do we start our tags with an ~ character? Because they get sorted to the end of the label list in the GitHub UI.
Any developers out there want to share their GitHub Issue protips?
- 8 comments, 7 replies
- Comment
@shawn, first time I've seen the async manifesto. I love it.
We were a waterfall shop until about six months before I joined, then the consultants came in and preached SCRUM, but what was instrumented was a very ritual heavy cargocult. Tons of meeting for very little gain, we called it scrumfall.
The PM's were not used to low process workflows, and it took a lot of evangelizing before I was able to get away with radical ideas like eschewing sprints for continuous delivery, and long planning meetings for short 15 minute backlog reviews.
We still do a daily standup, but it's for the devs to unblock each other more than anything else. The PO barely attends, because they can just glance at the board.
Now, the PM/PO's understand the value of a well-defined story, and know that anything they put at the top of the stack will be in production in 1-3 days, so everyone wins.
The only struggle we have now is prioritizing non business features into the workflow. As an attempt to address this, I've instituted what we are calling "Tech Debt Burndown Day" as the last friday of every month.
The dev team puts known tech debt items on our wiki throughout the month, and the day before we do a quick 30 minute stack rank of our debts. I block the calendars for the entire dev team on the day, and everyone focuses on burning through the backlog. It's a fun day, with a catered lunch and some booze.
Happy devs = productive devs.
As a non-developer in the project, I'm still arguing for only two priority levels: high & low. Medium feels wishy-washy.
At least it's not seven priorities, like FogBugz: http://discuss.fogcreek.com/FogBUGZ/default.asp?cmd=show&ixPost=789&ixReplies=1
I think number of priority levels depends largely on use case. Some projects or people need more granularity, especially as volume increases
i need more granularity when there are more issues. i get decision paralysis.
On one of my side projects we have 5 priority levels. Since I only work on it a couple hours a month, they're very useful in helping me figure out what my colleague needs me to do.
The ice box is for stuff we wish to someday be able to work on, but will probably never get to. You might think we should just leave those out of the issue tracker, but having them recorded keeps us from working on them when we have more important things to do.
I do wish Github would allow manual ordering of issues, so we could just order by priority.
We also have "project-*" labels. There has to be a signed SOW for projects in order for us to work on something, so even if the priority is high, I have to check the project label and make sure it's an active project or else skip it.
Lastly, we have status labels... which we should probably start prepending with "status-"... but it's stuff like "needs-clarification", "on-hold", "in-pull-request", and "in-progress". "needs-clarification" is important because we don't want to reassign the issue to the person who needs to clarify for us, but it lets them easily see that we're waiting on them.
We are using a kanban board now, and don't have a priority field. Our product owners just rearrange the cards in the ready for dev column and we always pick from the top.
I've spent the last few months slowly destroying SCRUM and minimizing the amount of process down to just a continual flow of stories. No more planning / grooming, just a stack ranked pile of work that is always being delivered.
@joneholland Reminds me of this I saw floating around a while back: http://asyncmanifesto.org
We're probably headed towards your direction as we get bigger, but right now I'm wearing the hat of the product owner, and the hat of the dev manager, and the hat of dev ops... and since I'm wearing lots of hats right now our silly little approach is helping me surface the important stuff to pay attention to.
@katylava To me, there's little difference in what you'd work on between 1 & 2 and 3 & 4 in your list. I feel like "urgent" and "not urgent" are almost always enough. Plus, you want to spend as little time as possible trying to decide what tag to give something, and even less time having a discussion with anyone over whether you chose correctly.
I do like the idea of a "maybe someday but possibly never" category, like your icebox, but that feels separate from priority and more like the bug/feature type.
@joneholland 1/30 days? Shit, I'm managing a project that's got 6 months of debt because of rushed decisions made years ago. No one will upgrade once we're done because there's no obvious benefit. It's being developed/refactored solely to give tech support a product that they can support without needing to involve the developer every time.
We've got no product owner, no product manager, no input from sales/marketing. No one wants to own it because it could make cannibalize some sales, as it makes our product line less "sticky". Sounds like a big win, right? Why are we doing it? Two reasons. First, many of our clients need this product, and they won't buy without it - but we've already got that checkbox checked, so to speak. So really, one reason. We've got a rock star developer who could be put to better use on a dozen other projects, and she's got the clout, foresight and chutzpah to tell everyone that she can't do that if she leaves an unmaintainable product behind if she's to be effective elsewhere. How can I argue with that? So 6-12 months of austerity measures it is.
@dave If there was no difference between 1-blocking and 2-asap... then I wouldn't know to work on the 1s first, which is important. Same goes for 3s/4s.
I agree you shouldn't spend too much time thinking about priority when you are creating an issue, but if it's high enough, you don't have to think hard, you just know. Otherwise, default to "low". You can always change it later.
As a developer, just being able to pop the next task off the stack is preferable, so I prefer systems where you can just put the issues in order... most important on the top.
For the project I was talking about before, we started off using Pivotal Tracker, which I like the most. Only problem is it looks more complicated than it is, so it scares off clients, and well, we needed them to be able to file issues.
PT has other benefits too, like telling me when I'm likely to actually deliver something.
But how do you decide which of the 1s to work on first? Should there be 1s and 1.5s? At some point you just decide.
generally, items within one priority have no relative importance to each other. but 1s really are more important than 2s, and so on.
also, in practice there are very few 1s and 2s.