- Epic is at the group level.
- Only group members can create and delete epics.
- An epic contains a required title and an optional description.
- An epic contains an optional start date and an optional end date.
- An epic is contains 0, 1, or more issues that are in the projects of that group, or in any other subgroup going down.
- An epic contains 0, 1, or more epics that are in the group, or in any other subgroup going down.
- An issue can be part of at most one epic. If an issue is added to an epic, it is automatically removed from any previous epic.
- An epic can be part of at most one epic. If an epic is added to an epic, it is automatically removed from any previous epic.
- If you have access to an issue, then you can add it to the epic.
- If you have access to another epic, then you can add it to the epic.
- An epic is created and exists, or it is deleted.
- When an epic exists, there is no state (at least for this iteration). In the roadmap view, you can see more relevant information for an epic: #3293 (closed).
- Review these specs and mockups carefully. Anything not specified is out of scope.
Latest mockups: #3255 (comment 41119063)
Some questions and responses
From #3255 (comment 41458580).
Thanks @dblessing for the great questions. Some responses. And also adding to the description since these are great illustrative questions.
Why are epics at the group level only? An epic in a project seems like a perfectly valid thing.
Our current strategy in Discussion is to really go after the use cases of large teams/organizations that are using GitLab. Often these teams are managing their work in groups (and multiple projects in those groups). So we want to address their needs with features like group boards, and now epics. So similar to boards, you are right, epics make sense at a project level too. But we want to go after these big-team use cases first from a product strategy perspective.
What differentiates an epic from a parent issue?
Essentially this boiled down to: Do we want to create a new first-class citizen abstraction of "epics/feature/whatever-name" vs linking issues together into a hierarchy, but not create any new abstractions? We've talked to customers and reviewed existing tools on the market. And also considered the roadmap view (#3293 (closed)) use cases. Essentially it's a much better experience for users to quickly have an abstraction of epics. So since this is the case, we won't consider parent issues / sub issues for now. And introduce first epics as a feature in GitLab. We shouldn't need need parent issues. But we can of course revisit later.
What differentiates an epic from a milestone?
A milestone is a group of issues associated with time. Milestones are focused on working on code within a time period, and shipping code on a certain date. So a milestone is less concerned about the actual content of the issues, how they interact, and how they are related together. A milestone is about the development process.
An epic is a group of issues grouped together because they relate to each other in theme/content. Essentially a "meta" issue as we've used meta issues up to know.
Again back to the roadmap view (#3293 (closed)), which is really driving the design of epics. The users of the roadmap view are CEOs, VPs, managers, business managers, etc. These folks care less about the actual specifics of code being released and the nuances there. They care that an entire epic has been delivered to a user. For example, a new Bitcoin payment system is now completed and in production for users, and it landed in Q3 of 2017. They care about this level of granularity. So we call this an epic and we display in the roadmap view that is now complete.
Feels like we’re adding a lot conceptual complexity. I believe users will find this confusing.
Yes indeed there is a lot of complexity. And there is a lot of new functionality. We are still following our GitLab principles of small quick iterations. But at the same time, we are doing the upfront work of talking with customers, reviewing existing tools on the market, and designing features that make sense for GitLab (and take advantage of our unique integrated platform strategy). So with each release, we are introducing new features, and we hope to make a big splash in 10.2, but we are still shipping in months, and not say, quarters. So that has not changed. We believe we are doing the best job we can in designing effective and usable features, to the degree that users will not find it confusing. But indeed this is subjective and your point is well-taken. But I don't think the risk is very high in that these features are existing concepts in the marketplace and we trust our users will recognize and use them.