Setting up your first ZenHub Epic

Using Epics for GitHub Project Management

Without ZenHub, your GitHub Issues are organized in a simple list. Which Issues are related or dependant? “Epics” are one of the most powerful tools for planning and executing on software releases and answering these questions.

ZenHub Epics are, to put it simply, a theme of work that contain sub-tasks required to complete the 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. In agile development, a “user story” is the smallest unit of work, and an Epic is essentially a “big” user story.from-issues-to-epics

We do this in ZenHub by creating an Epic to map out bigger goals, then adding related GitHub Issues to flesh it out.

Below, you'll learn how to combine ZenHub Epics and GitHub Issues, markdown checklists, and GitHub Milestones to ship better software with less overhead.

What's in an Epic?

Three main concepts work together to form an Epic. In agile, we know these as Epics, User Stories and Sub-tasks. In GitHub and ZenHub these concepts are reflected as Epics, GitHub Issues, and Markdown Checklists.epic-in-github

Epics help bring together tasks to form a more powerful GitHub Issue management system. This helps you plan and execute your product backlog and sprint work more effectively.

But first, a note on GitHub Milestones and ZenHub Epics. While they seem similar at first glance, their purpose is different. In fact, they function best when used together!

You can also set up Learn more about agile concepts in GitHub and ZenHub to master your ZenHub workflow.

Epic or GitHub Issue?

Not sure whether a GitHub issue should become an Epic instead? First, consider the time it takes to complete a task and it's 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 is too complicated (if multiple tasks are required to finish it), it's probably better as an Epic. Splitting tasks into easily completed pieces of work will help you ship valuable changes more often and reduce technical debt.

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. Sprints move teams toward a goal of shipping business value (features) to the user. In GitHub, Milestones are how we plan and execute sprints. So remember, when we talk about GitHub Milestones, we're talking about sprints.new-milestone

Since milestones are tied to sprints, they contain Issues related by time, and not necessarily related by subject. The scope of work is fixed once a sprint begins.

In contrast, 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.

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. 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.

Creating Epics in ZenHub

To create Epics in ZenHub, get started by creating a New Issue. The New Issue button is how you create both tasks, as well as Epics. At the bottom of the new Issue creator is an option to submit as a new Issue or create an Epic. Select Create an Epic to create a bundle of work and move to the Epic builder.create-new-epic

Once you create an Epic, you enter the Epic builder. The list presented will display all Issues within your Board, orgnized by pipeline. You can add Issues already existing in your workspace by selecting the checkbox next to each Issue. Navigate between pipelines by clicking on their name on the navigation to the left of the list, or leverage the top filters to search for specific Issues by label, Milestone, or assignee.

You can also rapid-add new Issues to this Epic by adding a title into the top Title bar and hitting enter, or clicking New Issue.

The left panel will begin to populate with the Issues you're adding to this Epic. You can add or remove to the Epic at any time from the Board or the Issue sidebar. When you're done with the initial setup of your Epic, simply click Create Epic on the left panel.epic-creator

Once created, you'll now have a new Issue on your Board with two distinguishing factors: a Epic label and a filter on the Issue card (Show all Issues in this Epic) that can be used to filter the board by all stories and tasks in that Epic.epic-on-the-board

When opening the Epic from the Board, you'll get a new list view that will show all stories and tasks within the Epic, which pipeline they are currently in, as well as associated information for these Issues such as their title, ID, and estimated story points.

At the top of the Epic is also a progress bar. There are two bars: one for Issues completed and another for story points completed. Learn more about estimating Issues with ZenHub here.new-milestone

As you start to interact with Issues, complete work, and go about daily activities such as stand-up or daily to-do planning, you can leverage the Board Epic filter to drilldown on story or project work that's been rolled-up into your newly created Epic.epic-filtering-on-the-board

How do I convert a GitHub Issue to an Epic?

If an existing story or Issue needs to be converted into an Epic, get started by opening the Issue page for that Issue. On the sidebar of the Issue is the Epics dropdown. Once selected, at the top of the dropdown is an option to Convert to Epic.How do I convert a GitHub Issue to an Epic?

When converting an Issue to an Epic, this new Epic will be nested within any Epics the Issue was originally in.

Nested Epics and Epic lists

Plan for multiple projects, add various levels of tasks grouped together, and have everything ordered in the same view as your Board. Epic lists are designed to provide information on where each Issue assigned to an Epic sits in relation to each other, across your pipelines.nested-epics-and-story-points

This makes it easy to tackle roadblocks, focus on what's up next, and visualize what other Epics are impacting project progress. When viewing an Epic, if there's a nested Epic, it will default to being collapsed within the list view. Simply click on Show Epic Issues to view all Issues belonging to the nested Epic.

Epic points vs. story points

Epic points are the sum of all estimated story points from all the Issues within the Epic, including any nested Epics. The Epic points completed status indicator summarizes all completed story points across the project. (Learn more about story points and estimates here).

Epic points give a summary of complexity of all Issue estimations that belong within a single Epic. At the top of the parent Epic, the Epic points completed represent the total story points of all nested Epics and Issues.nested-epics-and-story-points