Epics project management guidelines

1. You are here:
2. Handbook
3. Marketing
4. Marketing Project Management Guidelines
5. Epics project management guidelines

On this page

• Background
  • Key things to know
  • Known Limitations
• Guidelines
  • Use the roadmap view for high-level overview
  • Associate all related epics in an ancestor relationship
  • Set the start and end date for epics
  • Use executive theme labels
  • Define weight for child issues
  • Set health status for child issues

This is a work in progress for the Marketing Project Management Simplification project.

Background

Epics provide a way to organize and manage a set of issues and sub-epics that share a strategic theme. In addition to logical grouping, epics enable project managers to perform higher level planning and build a roadmap with visual status tracking.

Key things to know

1. Epics are defined at the group level
2. Epics can now be made confidential (when created from epics > Create New)
3. Epics can contain both issues and epics as children
4. Epics can be used as a filter in both issue lists and issue boards
5. Epics provide visibility on: child epic and issue status, roadmap timeline (Gantt chart)
6. An epic is visible on a roadmap view if it contains a start or due date - all marketing roadmap here
7. Child epics are also visible on a roadmap view, nested under their parent, when they have a start or due date
8. The roadmap view provides a timeline of epics as well as completion status of each based on aggregate issue weight completion for issues linked to the epics
9. The roadmap view is available on the individual epic and on the group page under Epics > Roadmap. The group page view provides additional filtering, sort order and timeline units for display
10. An issue can only be assigned to one epic
11. Epics can have multiple child epics up to a depth of 5

Known Limitations

1. Epics cannot be created from templates (issue) however, there are three workarounds
   1. First - Epics Can be created from an issue that is promoted to an Epic. (in this case, an Issue Template could be a surrogate for an Epic template)
   2. Second - The mixture of issues related to an epic can be templatized in a spreadsheet and uploaded to populate the issues related to a given epic. See this epic template overview - note for collaborative epics that span multiple GitLab projects/teams: with this process, for the total number of projects/teams the issues span, you will need to complete that number of uploads of the spreadsheet, broken out by project/team.
   3. Third - Include code for the epic in the relevant handbook page to be copy/pasted, with issuable template hyperlinks. See this handbook page for an example
2. Epics do not have an assignee
3. Epics cannot be created in projects (issue)
4. Epics cannot be cloned (issue)
5. Epics cannot contain issues from above their parent group (issue)
6. Feature request: calendar view (issue)

Guidelines

Use the roadmap view for high-level overview

The roadmap view can serve as the single source of truth and as a high-level overview to effectively understand the strategic themes, OKRs, marketing projects, and campaigns the team is working on.

A single link to the parent epic or to a group's roadmap page with (optional) filtering can be used for leadership visibility.

Milestones and issue boards can then be used to drill down into the details for more granularity on individual task status.

Associate all related epics in an ancestor relationship

All epics that are related to an OKR epic or a strategic theme epic should indicate just one of them as the ultimate ancestor in order to align them properly on the roadmap.

Set the start and end date for epics

In order for the roadmap view to be displayed and to provide meaningful visual timeline information, explicitly add the start and due dates to epics during the planning process.

Use executive theme labels

All epics that are part of a strategic theme or an OKR should they carry the associated executive label, so that they can be filtered on the roadmap view. Optionally they can also carry one or more of the approved group-level labels.

Define weight for child issues

As an additional piece of information to track completion status, the roadmap offers a completion percentage based on the weight of the children issues that have been completed over the total issue weight of all direct descendant issues combined.

It's recommended to set the relative issue weight for all child issues to be able to track and report epic completion on the roadmap view.

Set health status for child issues

It can be good practice to highlight issues that need attention or might be at risk before a status review. This information can then be displayed on the roadmap view. For this to work, a health status can be assigned to individual issues.

A known limitation is that health status cannot be set via quick actions (issue), but it can still be easily set via the web UI.