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!
This article was originally posted on www.zenhub.com and updated in June, 2021.
Next, 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.
- Sprints are used to track the progress of issues and pull requests. They contain issues related by time, and not necessarily related by subject. The scope of work is fixed once a sprint begins.
- Epics contain issues related by subject, and the scope is flexible.
In order to use Epics and sprints effectively, we need to step back and look at what they’re made up of: GitHub Issues.
Going back to the heart of the Issue
As we’ve discussed, we suggest using a user story as the title for your GitHub Issues — that is, high-level feature descriptions that help define benefit from a customer’s perspective. Remember, once a sprint begins, its scope should remain fixed.
But why do we keep coming 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.”
Making GitHub Agile
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!
