Arrow left
Blog Homepage

Taking your GitHub issues from good to great

Taking your GitHub issues from good to great

Editor’s note: This blog post was originally published in July 2016 and has been completely revamped and updated for accuracy and comprehensiveness.

This article is an excerpt from our new book. For the full guide to building a collaborative software team, pick up your free copy!

Issues, GitHub’s task-tracking system, are a powerful wrench in any developer's tool belt. But while their simple structure makes it easy for others to weigh in, issues are really only as good as you make them.

Without some process, your repository can become unwieldy, overflowing with duplicate issues, vague feature requests, or confusing bug reports. Project maintainers can become burdened by the organizational load, and it can become difficult for new contributors to understand where priorities lie. It's a challenge for any team, but becomes especially difficult when that project is open source.

In this article, we'll share how to take your GitHub issues from good to great.

The issue as user story

We spoke with open source expert Jono Bacon – former Director of Community at GitHub and XPRIZE, author of The Art of Community, and strategy consultant.

“High-quality issues are at the core of helping a project to succeed. While some may see issues as merely a big list of problems you have to tend to, well-managed, triaged, and labeled issues can provide incredible insight into your code, your community, and where the problem spots are.”

He continues, “At the point of submission of an issue, the user likely has little patience or interest in providing expansive detail. As such, you should make it as easy as possible to get the most useful information from them in the shortest time possible.”

A consistent structure can take a lot of burden off project maintainers, particularly for open source projects. At ZenHub we’ve found that encouraging a user story approach helps make clarity a constant.

As we've discussed before, the common structure for a user story addresses the “who, what, and why” of a feature: As a (user type), I want to (task) so that (goal).
Here's what that looks like in practice:
As a (customer), I want to (create an account) so that (I can make purchases).

We suggest sticking that user story in the issue's title. You can also set up issue templates to keep things consistent.
ZenHub Issue

The point is to make the issue well-defined for everyone involved: it identifies the audience (or user), the action (or task), and the outcome (or goal) as simply as possible.

Qualities of a good issue

Not all issues are created equal — as any OSS contributor or maintainer can attest. A well-formed issue meets these qualities outlined in The Agile Samurai.

Ask yourself if it...

  • is something of value to customers.
  • avoids jargon or mumbo jumbo. A non-expert should be able to understand it.
  • “slices the cake,” which means it goes end-to-end to deliver something of value.
  • is independent from other issues if possible. Dependant issues reduce flexibility of scope.
  • is negotiable, meaning there are usually several ways to get to the stated goal.
  • is small and easily estimable in terms of time and resources required.
  • is measurable; you can test for results.

What about everything else?

If an issue is difficult to measure or doesn’t seem feasible to complete within a short time period, you can still work with it. Some people call these “constraints.”

For example, “the product needs to be fast” doesn’t fit the story template, but it is non-negotiable. But how fast is fast? Vague requirements don’t meet the criteria of a “good issue”, but if you further define these concepts — for example, “the product needs to be fast” can be “each page needs to load within 0.5 seconds” — you can work with it more easily. Constraints can be seen as internal metrics of success, or a landmark to shoot for. Your team should test for them periodically.

What’s inside your issue?

In Agile, user stories typically include acceptance criteria or requirements. In GitHub, we suggest using markdown checklists to outline any tasks that make up an issue. Issues should get more detail as they move up in priority.

Say we’re creating an issue around a new homepage for our website. The sub-tasks for that task might look something like this.
GitHub Issue

If necessary, link to other issues to further define a task. (GitHub makes this really easy.)

Defining features as granularly as possible makes it easier to track progress, test for success, and ultimately ship valuable code more frequently.

Once you’ve gathered some data points in the form of issues, you can use APIs to glean deeper insight into the health of your project.

“The GitHub API can be hugely helpful here in identifying patterns and trends in your issues,” says Jono. “With some creative data science you can identify problem spots in your code, active members of your community, and other useful insights."

Some issue management tools (including ZenHub) provide APIs that add additional context, like issue estimates or the historical movement of issues across kanban boards.

Getting others on board

Once your team decides on an issue structure, how do you get others to buy in? Think of your repo’s ReadMe.md file as your project’s “how-to”. It should clearly define what your project does (ideally using searchable language) and explain how others can contribute (by submitting requests, bug reports, suggestions, or by contributing code itself.)


This is the perfect spot to share your GitHub issue guidelines. If you want feature requests to follow the user story format, share that here. If you use a tracking tool to organize your product backlog, share the badge so others can gain visibility.

“Issue templates, sensible labels, documentation for how to file issues, and ensuring your issues get triaged and responded to quickly are all important” for your open source project, says Jono.

Remember: it’s not about adding process for process’ sake. Some simple guidelines can help others discover, understand, and feel comfortable contributing to your community.

“Focus your community growth efforts not just on growing the number of programmers, but also [on] people interested in helping issues be accurate, up to date, and a source of active conversation and productive problem solving.”

Pssst! If you haven't already, download ZenHub free to get task boards, epics, and more – directly added to GitHub.

We'd like to send a huge thank you to Jono Bacon for providing your thoughts! 👏

Featured image by Othree under CC by 2.0 license.

Software Development
Newsletter Icon