Note: Zenhub's full feature set is unlocked when you connect your GitHub Organization to Zenhub
TABLE OF CONTENTS
What are Epics?
Epics are an overarching grouping of tasks (or sub-tasks) that contain several smaller “Issues,” also known as “user stories” in agile development. Epics represent larger goals that may span multiple or single sprints (sprints are typically 2-6 weeks). In Zenhub, Epics are smaller than a “Project,” which is a grouping of several related Epics and larger than a single issue.
The concept of “Epics” stems from the agile principle that tasks should be broken down into small, manageable chunks. Ultimately, an Epic’s purpose is to enable teams to ship small, impactful changes more often and gain more control over the release cycle.
Three main concepts work together to form an Epic. In agile, we know these as Epics, user stories, and sub-tasks. In Zenhub, these concepts are reflected as Epics, Issues, and checklists (which live inside issues).
Creating a new Epic in Zenhub
Here are a few ways you can create a new Epic in Zenhub:
From the board's menu:
From your Kanban board, you can select the “+” in the top right corner. From here, you will have the option to “Create…Epic.”
From the Epics menu
From the Epics menu (on the left-hand side of Zenhub), you can select “New Epic.”
Keyboard shortcut
The keyboard shortcut for creating an Epic is N + E.
From the roadmaps menu
From the Roadmaps menu, you can select the “+” beside “Projects and Epics,” which will give you the option to “Create in roadmap…New Epic.”
Adding information to a new Epic
When creating an Epic, there are a few key pieces of information you’ll want to add to ensure your team understands the scope and timeline of the Epic. Consider adding:
Timelines: This is the timeline for how long a project will take (all the Issues combined) and not a single Issue. You can select both a start and an end date from the Epics page or from the Roadmap.
A “Project”: If your Epic is part of a larger initiative, you can select that initiative under “Projects.”
An Epic estimate: Epic points give a summary of the complexity of all issue estimates that belong within a single Epic.
Assignees: Choose who is primarily responsible for the completion of the Epic.
Labels: Choose which GitHub labels are most representative of the Epic.
Adding Issues to Epics
Once you have created an Epic, here are a few ways to add Issues to your Epic:
Create new Issues from the Epic's page:
From the Epic’s page that you have created, you can create a new Issue that will be automatically added to it by selecting “New GitHub Issue” or the “+” button for the option to create a Zenhub Issue (an Issue meant for non-development work).
Select “Epic” from the Issue menu:
If you already have an Issue created, you can click on that Issue, go to the Issue’s page, and on the right-hand side, you will see “Epics.” Click on the gear icon, and you will be able to add that issue to one or several existing Epics.
Select multiple Issues from the board:
If you have multiple issues you’ve already created and wish to add to your Epic, you can simply go to your board, hold down the “Shift” key and select multiple Issues. Once your Issues are chosen, select “Set Epic” from the top navigation. From here, you will be able to add all these Issues to any existing Epic.
Adding Epics to Roadmaps
Want full visibility into all projects happening on the same timeline? When you select the “+” from the roadmaps page, you will have the option to add Epics to your roadmap from your workspace and other workspaces in your organization.
Epics FAQs
What's in an Epic that’s not in an Issue?
Epics also contain other information that isn’t contained in Issues, such as:
“Timeline” – the date you wish to have your Epic completed by
Epic progress – This shows how many Issues total have been completed in this Epic and how many story points have been completed. Zenhub uses your team’s estimated velocity to calculate whether or not a project is on track to be finished on time.
“Project” – This is a collection of Epics that the Epic may live under if it’s part of a larger initiative.
Epic, Issue, or Project?
Not sure whether an Issue should become an Epic or a Project instead? Here’s how:
Consider its complexity and the time it takes to complete the task.
When a goal or task can be broken down into smaller chunks, it is typically called an “Epic,” which is essentially a “big” user story compiled of smaller ones. If the task is too complicated (i.e., if it can be divided into multiple tasks), it's probably better as an Epic.
Issues should be completed in the smallest amount of time possible. If it takes weeks or more to finish, it should be an Epic. Splitting tasks into small chunks of work helps you ship valuable changes more often and reduce technical debt.
So, what is the difference between a Project and an Epic? A Project is basically a collection of Epics. For example, you may have a really large feature you’re trying to release. And that very large feature consists of smaller features. And those smaller features can be further broken down into individual tasks to be worked on. In that case, the largest feature is your Project, and the supporting features are Epics, and everything inside those Epics are Issues.
Does there always need to be an Epic and/or Project?
No. You may have individual one-off issues that don’t level up to an Epic, and you may also have Epics that don’t support larger initiatives. Use Epics and Projects as they best fit into your team’s work.
The difference between Epics and Sprints
Sprints and Epics aren't interchangeable. In fact, they work best when used together! In an agile framework, a Sprint is a timeframe in which work is completed and typically lasts 2-4 weeks with the goal of shipping workable code by the end. These iterative changes are the cornerstone of agile development, moving teams toward the goal of shipping value (features) to the user. Zenhub Sprints allow teams to automate their sprint planning process so it occurs on a regular schedule. Learn more about Sprints here.
Since Sprints are tied to short iterations of work, they contain Issues related by time and not necessarily subject matter. In contrast, Epics contain Issues related by the subject matter, and the timeframe and scope are flexible. You may be working on multiple Issues that span multiple Epics within the same sprint.
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 the 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 Issues within an Epic.
Related resources
Intro to Sprint Planning in Zenhub
Intro to Issue Estimation in Zenhub