Epics and roadmap are two newer features in GitLab Ultimate and GitLab.com Gold. Used together, your team can plan and track larger initiatives. On September 22, we're shipping a new feature which we will help you transition seamlessly between top-down and bottom-up planning.
First things first: epics vs. issues vs. roadmap
An epic is similar to an issue in that it records a proposed scope of work to be done, allows for team members to discuss that scope, and then is tracked and updated over time as that work is actually implemented.
However, an epic exists at the group level (as opposed to an issue, which exists at the project level). So immediately you see that an epic is designed to reflect a larger scope, and higher level of discussion compared to an issue. Additionally, you can attach any number of issues to an epic, with the idea that the epic's scope decomposes into those individual issues.
Since an epic is designed to scope work over a longer period of time (several issues' worth), a timeline-based view in the form of a roadmap is also useful: it serves as a visualization to anticipate that work, and track it as it's progressively completed. So the roadmap, also scoped at the group level, presents all the epics in time for that group.
You can apply group labels to epics, making it easy to quickly narrow down to the epics you care about, whether you are looking at a list view or a roadmap view.
Long-term vs short-term planning
When planning any initiative, uncertainty, by definition, increases further out in the future. You don't know how many resources you will have. You don't know if previous dependent work will be finished. You don't know if the market and your customers will change such that you won't even need that planned out initiative at all.
Conversely, the nearer-term future is much more certain. You have a good handle of the work that should be accomplished and that it can be completed within the next few weeks, up to a month or so.
And of course, the work you are doing now, and have already completed in the past, has zero uncertainty. You can't change the past.
Epics and roadmap help you plan and track work in all these cases:
Long-term future: top-down planning
When planning far in the future, we use top-down planning. We have strategic initiatives
that we want to achieve, with approximate scope and timelines. So in this case, you would
create an epic, and assign
Fixed dates (a planned start date and planned finish date) to it.
The epic would appear in the roadmap view, and you would be able to see it positioned further
in the future.
This helps high-level planning, such as starting discussions with various departments in your organizations, or presenting a strategic roadmap to your executive leadership. By creating the epic early on, it provides a collaborative space for all stakeholders to discuss feasibility and further detailed ideas.
Short-term future: bottom-up planning
When planning for the nearer-term future, we use bottom-up planning. So suppose the epic you created previously with fixed dates has gained some traction within your organization. People are excited about the prospects and want to flesh out detailed designs and implementation steps. You and your team would then start creating issues and attach them to the epic.
Eventually, you have scoped out the detailed work in the issues and even assigned milestones to them,
indicating when they are planned to be worked on. Now, instead of having to manually update the epic
to reflect the milestone dates, you would simply choose
From milestones in the epic sidebar. In this
case, the epic planned start date becomes a dynamic date reflecting the earliest start date across all
the epic's assigned milestones. The same goes for the epic's planned end date too.
This functionality is coming in GitLab 11.3 – you can view the original issue here.
Additionally, the roadmap bar edges will reflect the fixed or dynamic start and end dates accordingly.
So with this design, you are in control when you want to seamlessly transition an epic from a top-down planning scenario, to a bottom-up one. The roadmap reflects these dates automatically too, so that all your epics are shown together in one view.