What is ZenHub Roadmaps?
A ZenHub Roadmap allows you to organize your projects and epics into a gantt-style timeline view so that you can plan out your organizations long-term product roadmap. A ZenHub Roadmap is based on the work your team is already doing in GitHub. Projects and epics are tracked by story points or issues completed, providing you with real time visibility into the progress of each project.
Learn more about how each member of the team can use Roadmaps here: ZenHub Roadmaps Use Cases
Benefits of ZenHub Roadmaps
Here are a few ways ZenHub Roadmaps helps teams:
- Plan your projects in advance. A Roadmap allows you to add your projects and epics to a timeline view, providing a complete visualization of current and future projects to help with long term business strategy.
- Accurately track project progress and eliminate status update meetings. By continuing to close issues and merge pull requests, the Roadmap will automatically reflect this completed work so that you can view the progress of individual projects at a glance.
- Provide stakeholder visibility into projects. By adding current and planned projects to your Roadmap you can communicate business strategy to all stakeholders involved. All team members will have a clear understanding of current projects in progress and the future product direction.
ZenHub Roadmaps Hierarchy
- Projects: A Project is a high-level plan with a desired start and end date. Projects help you to envision your future plans. The scope of projects may not yet be defined and you can modify project start/due dates as you and your team uncover more about the project and begin fleshing out its scope.
- Epics: An epic is a theme of work containing sub-tasks (issues) required to complete the larger goal. Adding epics to a project allows you to accurately track project progress. By closing issues that have been added to your epics, the Roadmap will reflect these changes providing you with valuable insights into the progress of your projects
When viewing a ZenHub Board, you can filter the Board by specific epics and the issues associated with these epics. Projects are not available in the Board filtering options. To view your ZenHub projects you must navigate to the Roadmap view as your projects live within the Roadmap.
Setting up a Roadmap
A ZenHub Roadmap is Workspace specific and this is created at the Workspace level. Using either the ZenHub extension or the web app, navigate to the sidebar where you will see the Roadmap option:
This will open up the Roadmap for your Workspace. By selecting the green + located to the top left of the timeline page you will be able to choose from four options: 1. Create a new project 2. Create a new epic 3. Add a project from a different Workspace to the Roadmap or 4. Add existing epics from your Board
Adding a project to a Roadmap
Projects are created at the Workspace level. Select Create new project to display the input field where you can give your project a name. Once you have chosen a title for your project, press Create Project. Note: There is a 100 character limit for project titles:
Your project name will appear in the projects list located to the left of the Roadmap. There are two ways to set the dates for your project:
- Click and drag on the Roadmap timeline to set the start and end date for your project:
2. Project option menu: By selecting the project option menu to the right of your project name, you can choose to set the start and end date for the project using the calendar view:
Adding epics to a project on the Roadmap
By adding Epics to your project you can accurately track the progress your team is making on that project. To add an epic to an existing project, select the + icon next to the project option menu. From here, you can choose to add an existing epic from your Workspace to your project or you can choose to create a new epic that will be added to your project :
Setting dates for epics
Set the dates for epics on the Roadmap by:
1. Setting the start and end date directly from the epic on the Board
When viewing an epic in your Workspace, select the set start and end date button when viewing the epic which will open up the calendar modal. From this view, set your desired start and end date for the epic. This will automatically add your epic to the Roadmap, providing your team with an at-a-glance progress report for your epic:
2. Clicking and dragging on the Roadmap timeline:
3. Using the epic options menu to set the dates for the epic:
Once an epic has been added to a project, they are tracked by story points or Issues completed within that epic. As you close issues and merge PR's the project progress will update to reflect these changes. Epics can also be added to the Roadmap as individual pieces of work, without being added to a particular project. This can be done by selecting the green + located in the top left of the page and choose to add epics to the Roadmap:
An epic can only belong to one project on your Roadmap. If you choose to add an epic to your project that already belongs to another project, you will be asked if you would like to remove the epic from it's original project and added to the selected project. This will impact all team members.
Expected behaviour when setting project and epic dates
- You cannot scale the timeline of a project to be shorter than the timeline of the epics associated with that project.
- When adding an epic with shorter start and end dates than the timeline of the project, the project will only inherit the progress of the epic.
- When adding an epic or modifying an epic to have a start or end date outside the timeline of the project, the project will inherit the start or end date of that epic.
- Projects and epics are sorted chronologically by end date. To prevent the appearance of projects & epics vanishing after creation, sorting is applied only after the Roadmap is reloaded.
Project options menu
Selecting the options menu next to a project will give you five options:
1. Remove the project from the Roadmap (If the project exists in another Workspace, you will be able to search for the project and add it back to the current Roadmap at a later stage.)
2. Set the start and end dates for your project
3. Rename the project.
4. Delete the project - This will impact all users and the project will be deleted for all team members.
5. Mark the project as complete.
Progress of projects and epics on the Roadmap
As team members complete issues, the Roadmap will automatically update to communicate project progress to all stakeholders. The green date line acts like a pace line in relation to the progress of your projects and epics:
- If the progress bars of projects/ epics are to the left of the date line, those projects/epics are behind schedule
- If the progress bars of projects/ epics are to the right of the date line, those projects/epics are ahead of schedule
With this information available, you can adjust the timeline to estimate when the projects/epics will be done by aligning the progress bar with the current date line.