Working with Epics in GitHub
Build and share product backlogs – inside GitHub
“Epics” are one of the most powerful tools for planning and executing on software releases. But they’re too often paired with clunky, bloated, decidedly non-agile tools.
So it’s unsurprising that Epics have been one of our most-requested features ever. Available now, ZenHub Epics make it easy to execute on product backlogs, providing a crucial “extra layer” of hierarchy to your GitHub issues.
Previously, GitHub users either had to jump into a third-party tool (a major distraction from the code), or use laborious workarounds, to do what an epic accomplishes. With this release, teams can now create epics directly from their existing GitHub issues, then get back to work.
ZenHub Epics add a crucial extra layer of hierarchy and planning ability to your GitHub issues.
The clearest path toward your next release
Before adding ZenHub, your GitHub issues have no real hierarchy; they’re simply a list. But which issues are related? Where do the dependencies lie? It’s difficult to say.
ZenHub Epics add a crucial extra layer of hierarchy to your GitHub issues, providing greater control end-to-end over the release process. Simply put, ZenHub Epics are a theme of work which contain several sub-tasks needed to complete the larger goal.
Creating an Epic from your existing GitHub data
Add existing GitHub issues to a new epic
When creating a new issue, you’ll notice a purple button: “Switch to Epic”. It’s a magical portal to the new Epic Builder.
The Epic Builder makes it easy to batch-add issues (displayed as a vertical task board) without jumping back into the main issues tab. Clicking the checkboxes on the right will add issues to your epic.
Top it up with new issues
But wait – you’re probably thinking. I don’t have all the issues I need for this epic — how organized do you think I am?!
We hear you — that’s where the Quick Issue Creator comes in. Add a title, then click “New Issue” to have it appear at the top of your list. (You can just go back later to add more detail.)
Next, add a description of that epic’s theme: a few lines communicating why these issues are grouped. Finally, click “Create Epic”! 🚀
From GitHub issue to ZenHub Epic
We’ve all been there: you started writing an issue, and halfway through, it’s starting to read more like a novel. But how do you know if you should turn your issue into an epic?
Firstly, each issue should take the smallest possible amount of time. If you estimate your issue will take weeks or months to finish, it should probably become an epic.
Similarly, if your issue is too complex — if several sub-tasks are required to mark it as “done” — it’s better off as an epic. By splitting each task into easily-completed chunks of work, you’ll reduce technical debt and be able to ship impactful changes more frequently.
Use the Epics drop-down on the right to convert an issue into an epic. (The issue’s existing text will display as a comment). You can also use this drop-down menu to add an issue directly into an existing epic.
Tracking progress and visualizing Epics
The most impactful part of epics isn’t creating them — it’s tracking them in an effective way.
With ZenHub Boards, you can view how epics fit into the big picture by seeing them alongside your other issues. By the same token, you can Filter by Epic to see only the issues inside it.
