GitHub Best Practices: Taking Issues from Good to Great

Editor’s note: This article is an excerpt from our newly revamped eBook: Project Management for Teams in GitHub. For the full guide to building a high-performing, agile 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 GitHub 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 extensive 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.

The point is to make the GitHub 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 of other issues if possible. Dependent issues reduce the 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’s 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 GitHub 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.

If necessary, link to other GitHub issues to further define a task.

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’s 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.”

Staying Agile with ZenHub Boards

Instead of tickets or sticky notes, the ZenHub Board is made up of your existing GitHub data: issues and pull requests that exist within the repositories that make up your Workspace. This provides you with a bird’s eye view of everything going on with your software projects.

The Kanban Board makes workflow visualization simple and accessible in real-time, empowering you to track issues and projects from an idea, through triage, to planning, development, and further to being released.

Getting Organized

Access your ZenHub Boards via the Board button (or, simply press Z+B on your keyboard).

On your ZenHub Board, you’ll see your GitHub issues depicted as individual cards. Dragging these cards from pipeline to pipeline represents where they sit in your workflow. Updates are pushed instantly to your team.

All your issues first appear on the far-left side of the Board, under New Issues. Let’s move them to their proper places!

New Issues: New issues land here automatically. They should be dragged to another pipeline as soon as possible.

Icebox: Low priority or unprioritized issues that are not to be worked on immediately

Backlog: Upcoming issues that are immediate priorities. Prioritize these issues through a top-to-bottom approach in the pipeline.

In Progress: This pipeline answers the question, “What are you working on right now?”. Ideally, each team member should be working on just one thing at a time.

Review/QA: Issues open to the team for review and testing. Usually this means the code is ready to be deployed pending feedback.

Done: Issues that are tested and ready to be deployed to production.

Closed: When an issue is closed, it will default land in the ‘Closed’ pipeline which is the last pipeline on the ZenHub Board. Closed issues cannot be moved to another pipeline unless re-opened.

When managing a large number of issues (not a bad thing!), take advantage of GitHub milestones.

A milestone is a collection of all the issues that your team will do within a sprint ( typically a 2 week period). Milestones are your sprints and sprints are your milestones.

You’ll then be able to filter by milestone (from the dropdown menu at the top of the Board) to see exactly what needs to be done during this timeframe:

Making It All Come Together

GitHub issues in your backlog should be arranged by priority, with the most pressing issues at the top. Issues get more detail as they move up in the pipeline.

Pin the highest priority issues to the top of a pipeline. During development or backlog refinement, teams often encounter one or more issues that require immediate attention such as a high priority bug.

To help teams highlight important issues and communicate the urgency of work, this ZenHub feature lets you pin an issue to the top of a pipeline:

During sprint planning, move Issues from your backlog pipeline to your sprint backlog pipeline (this pipeline is dedicated to work that will be completed in your next sprint) until the total number of story points in your sprint backlog equals your average velocity.

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