Arrow left
Blog Homepage

Beginner's guide to using Epics and Milestones in GitHub

Beginner's guide to using Epics and Milestones in GitHub

Editor’s note: This blog post was originally published in June 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!

In this article, we’ll show you how to create a lightweight and powerful GitHub workflow using Epics and Milestones. By applying some basic agile principles, you can combine Epics, issues (as user stories), markdown checklists (as sub-tasks), and GitHub Milestones to ship better software with less overhead. Read on to learn how we do it!

The difference between Epics and Milestones

One of our most common questions is how Milestones and Epics interact. Sometimes they're even confused for one another. Milestones and Epics aren't interchangeable; in fact, they work best when used together.

In an agile framework, a sprint is typically 2-4 weeks of work with a goal of shipping workable code by the end. These iterative changes are a cornerstone of agile development. In GitHub, Milestones take the place of sprints.

creating a ZenHub Milestone

Milestones 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 in subject, and the scope is flexible. Issues can be added or removed as teams discover more about the bigger goal.

In order to use Epics and Milestones 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

In GitHub, issues take the place of user stories – high-level feature descriptions that help define benefit from a customer’s perspective. Remember, once a sprint (Milestone) begins, their scope should remain fixed.

Let's touch on what that means in practice.

The issue as user story

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>.”
For example:
“As a <customer>, I want to <create an account> so that <I can make purchases>.”

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

setting up a ZenHub Issue template

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. There’s no need to obsess over this structure; other alternatives have been proposed. As long as the what and why of a story are easy to spot, you’re good.

To learn more about why a user story format is useful, 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.”

What's in an Epic?

Three main concepts work together to form an Epic.

Agile: Epic > User Story > Sub-Task

GitHub and ZenHub: Epics > GitHub Issues > Markdown checklists

Note: Without ZenHub, your GitHub issues lack hierarchy; they’re simply a list. There’s no clear indicator of which issues are related and where the dependencies lie. ZenHub’s Epics add this crucial layer of hierarchy.

![Agile vs GitHub] (https://dxssrr2j0sq4w.cloudfront.net/3.2.0/img/guides/achieve-more-with-epics/epic-in-github.jpg)

Working with epics in ZenHub

In agile, a user story is the smallest unit of work, and 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 contains issues (stories) needed to complete that larger goal. The concept stems from the agile principle that tasks should be broken down into small, manageable chunks; that way, you're able to ship impactful changes more often and ultimately gain more control over the release cycle. They keep product backlogs coherent and organized while providing greater control end-to-end over the release process.

Issue, or Epic?

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.

A sample workflow using Epics and Milestones

Here’s an example of how Milestones and Epics interact. Let’s say we’re redoing ZenHub’s website as part of a rebranding effort.

An Epic might be called “Website redesign”. Inside that Epic, I create one issue for each page in that website:

a Website redesign ZenHub Epic with an issue for each page of the website
As I add issues to my Epic, I'll also create markdown checklists of tasks needed to complete that page.

creating markdown checklists of tasks that need to be completed

At the beginning of a sprint, my team will create a Milestone (ie "Sprint 3"). Having already estimated complexity on the issues in our backlog, we’ll decide as a team which issues should be included in our Milestone. We use Velcoity charts, which give us a pretty good idea of how many story points we can tackle in a given sprint.

Software estimation through story points in ZenHub

We clearly can’t complete the entire website in two weeks, but finishing the homepage seems reasonable.

We’ll add the Homepage issue to our Milestone, and perhaps a couple of unrelated technical fixes. Together, these issues form a chunk of work that, based on our team’s projected velocity, we believe we can finish, test, and ship over the next two weeks.

Milestones and Epics aren't swappable concepts, but they are complementary.

The benefits of pairing Epics and Milestones

Once you understand the differences between Epics and Milestones, you’re ready to use both of them effectively.

Epics are intended to give you a broad understanding of larger initiatives. When paired with Milestones, you’re able to work towards these bigger goals in manageable iterations. This means you deliver more business value (e.g. workable code) more frequently.

If you use Epics without Milestones, you might get bogged down in details as you pursue big chunks of poorly defined work.

If you use Milestones without Epics, it's hard to effectively plan or pursue bigger goals. It's also more difficult to visualize how big chunks of work are progressing alongside all your other tasks. The lack of direction could lead to unclear priorities.

However, pairing Milestones with Epics gives you a granular way to plan and achieve your product backlog. It clarifies both the big picture and the minute details that make it up, providing everything necessary to ship better projects faster.

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

If you liked this post, subscribe to our monthly newsletter to receive more like it.

Project Management
Newsletter Icon