Without ZenHub, your GitHub Issues are organized in a simple list. Which Issues are related or dependent? “Epics” are one of the most powerful tools for planning and executing on software releases and answering these questions.
ZenHub Epics are 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.
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 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.
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.
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, select the + icon next to the New Issue button located at the top right of the Board. From here you can give your Epic a title and description.
Once you create an Epic, you enter the Epic builder. The list presented will display all Issues within your Board, organized 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.
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 (Filter by Epic Issues) that can be used to filter the board by all stories and tasks in that Epic.
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. Issues and Epics that are not in a repo connected to your Workspace will appear under the “Issues not in this Workspace” label.
When viewing an Epic you may also see a heading named Issues not in this Workspace. Issues that are a part of the Epic but not a part of a repo in the current Workspace you are viewing will be listed here. Issues within the current Workspace will continue to be listed under their respective pipeline name.
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.
You can also collapse the Epic section at the top of the Issue if you don't need to see the complete list of Issues. The progress bar will remain at the top of the Issue, so you will still see overall how the Epic is progressing.
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:
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.
When converting an Issue to an Epic, this new Epic will be nested within any Epics the Issue was originally in.
Need to convert an Epic back to an Issue?
You can convert an Epic back to an Issue by opening up the Epic, and using the Convert to Issue option in the Epic box that will appear once the Epic loads.
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.
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.