GitHub Issues features are amazing. Ticket tracking is a very hard thing to deal with – a project needs to hear from its users in order to help with feedback and prioritization of work. That they provide the feature at all is awesome. But they’ve also done a great job of linking a given issue or pull request to the branch, code, and users involved. Merging is easy, especially if you’ve enabled Travis CI integration. I can’t fathom how projects managed in the days of having these tasks spread across multiple sites and servers.
But there’s a big problem – it’s far too easy to ignore a project’s Issues page.
Just ask Jasmine’s userbase.
For example, I know a lot of what I want to fix about Jasmine. Between having Rajan in the office near me and having a few dozen projects at Pivotal Labs using it, I get lots of important feedback daily. There’s a public backlog at Pivotal Tracker. I often completely forget about this “other Inbox” at GitHub that’s just as important.
So Jasmine’s Issues page becomes like a garage – a place I’m afraid to look into because it’s just a big pile of work instead of a useful forum between us and our users. It’s been hard to get in there to find more problems, help people and find great code that should be added to the project.
I took some time recently to clean out our Issues. If you follow Jasmine on GitHub, you may have a full email Inbox.
There are some patterns and some techniques that I’m using to help get the number of open issues down to something manageable:
Problems, Help, Discussions and Questions
Occasionally there are stories that aren’t Jasmine problems. They can be “how do I test x”? questions. Or “when I do this in Jasmine, this happens. Why?” These aren’t Issues, but discussion topics. We want these to happen in a forum with a larger audience. There are more people subscribed to our mailing list than there are watching our Github issues pages. So we move the discussion and close the issue.
Feature Requests
If the Issue is an explicit feature request I add a story to our backlog and close the issue. I keep a link to the issue in the story – we want the full context to be available. This is acknowledgement that we’ve heard the feedback and will consider it. Let’s close the Issue and move on.
Bugs
Like feature requests, Bugs need to get into Tracker so that the team can prioritize and work on them. This can include pull requests. But if the item is already in Tracker, it doesn’t need to be an open Issue.
Duplicates, including Already in Tracker
If something has been discussed before and there was a conclusion – which can include a story already being recorded in Tracker – then there’s no reason for it to stick around. We label them as duplicates, link to the story in Tracker, and close the issue.
Simple, Obvious, Well-formed Pull Requests
If the pull request makes sense in the spirit of the project, simple enough to understand with a quick read, has tests, and is green according to Travis, we’ll take it. But “obvious” is still a relative term.
Everything Else
That just leaves everything else. This should be a list of truly open issues. These include us asking for improvements or re-implementing a pull request on top of current master, further testing, or deep discussions of potential features – just try and follow the threads about the feature request to run “just this one spec”.
(Note that for our own tracking, we put the label “WAITING” on issues where we are waiting for a response. The goal is to keep up with these as email notifications come in and have this label reflect the current status.)
If you’re a Jasmine user and have been frustrated with our (lack of) responsiveness in the past, I’m sorry. Please Know that we’re trying to get better and this post explains some of the “how.”
If you’re managing your own open source project, I recommend the amazing GHI which I discovered on the blog One Thing Well – being able to work through the issues on the command line has made the categorization much faster for me. YMMV.
After several hours combing through Jasmine’s Issues, I can see the floor and maybe even the back wall of our garage. And you should be able to gauge the project’s health better.
Now for my own garage…
