Agile Epics and Sprints in GitHub: a Guide

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!

In this blog, we’ll show you how to create a lightweight and powerful workflow using Epics and sprints.

By applying some basic Agile principles, you can combine Epics, issues (as user stories), markdown checklists (as sub-tasks), and sprints to ship better software with less overhead. Read on to learn how we do it.

But first…

Remember, a sprint is typically two to four weeks of work with the goal of shipping workable code by the end. These iterative changes are a cornerstone of Agile development. Here’s a summary of Agile Epics and sprints:

• Sprints are used to track the progress of issues and pull requests. They contain issues related to time, and not necessarily related to a subject. The scope of work is fixed once a sprint begins. You can now automate your sprints in Zenhub.
• Epics contain issues related to a subject, and the scope is flexible.

In order to use Agile Epics and sprints effectively, we need to step back and look at what they’re made up of: GitHub Issues.

Improving GitHub Issues

As a best practice, we suggest using a user story as the title for your GitHub Issues – that is, high-level feature descriptions that help define benefits from a customer’s perspective. Remember, once a sprint begins, its scope should remain fixed.

But why go back to the traditional user story format? To learn more about why it matters, we spoke with product management expert Alexander Cowan – faculty at the University of Virginia Darden and Managing Director at Synapse Partners.

“It’s important to remember that user stories are there to drive team discussions about what is a valuable outcome for the user,” he says. “They’re not just another format for a specification; specifications are about output and that’s why spec-driven products miss the mark so often with the user.”

To illustrate this concept, he suggests a simplified example of a website that sells something. In this example, a related story might be: As a [buyer persona], I want to [see my final items and charges] so I can [make sure I have what I wanted, and agree with the applicable charges.]

Alex elaborates, “That’s a good starting point for a team to design solutions for that part of the buying experience. A specification-driven approach would probably say something like ‘The page must show item descriptions, quantities, costs as well as tax and shipping.’ It seems fine too, doesn’t it?”

“A developer given that specification will probably build something that does all those things. But is it easy for the user to understand? Does it play well with the rest of the experience? Those are the kind of questions where specifications don’t perform as well. You usually end up with something that’s not wrong, per se, but just is not very good. And that’s not good enough anymore in today’s hyper-competitive marketplace.”

To learn more about improving GitHub issues, read this blog on GitHub issues best practices.

Practicing Agile in GitHub

To review, this is how we map Agile concepts to GitHub/Zenhub:

Note: Without Zenhub, your GitHub issues are simply a list with no indication of dependencies. Zenhub’s Epics and Dependencies add this crucial layer of hierarchy.

Working with Epics in GitHub

If a user story is the smallest unit of work, an Epic is essentially a “big” user story. If “as a customer, I want to be able to create an account” is a user story, the entire account management feature may be an Epic.

In Zenhub and GitHub, Epics are a theme of work that contain Issues (stories) needed to complete that larger goal. They keep product backlogs coherent and organized while providing greater control end-to-end over the release process.

As you can see, we now have three hierarchical layers: Epic, Issue, and sub-task (which can be linked to their own issues if necessary.)

So: Issue or Epic?

The eternal question. When deciding whether an issue should become an Epic (or vice versa), consider the time and complexity.

Issues should be completed in the smallest amount of time possible. If an Issue will take weeks or months to finish, it should probably be an Epic. Likewise, if an Issue becomes too complex – if there are several tasks required to complete it – it’s likely better off as an Epic. Splitting these tasks into easily-completed chunks of work helps reduce technical debt and ensures you can ship impactful changes more frequently.

Download our free eBook to learn more about creating workflows with Epics and sprints right in GitHub with Zenhub!