Epics

mentioned in issue #3254

marked this issue as related to #3254

mentioned in issue #2036

We likely need an first-class abstraction for "epics", instead of just recycling the issue object. Main driver is that when you create/view Gantt charts, we want a super simple way to pull in multiple issues that are associated from a feature perspective.

Milestones group issues together in time.
Boards group issues together to be executed by a single team.

When looking at a Gantt chart, milestones are helpful to know when things are projected to be done. But if you want to know that a particular are of your software, a feature/product area, there's currently no abstraction to group multiple issues together in that way. You can use labels. But that makes for a poor experience when dealing with Gantt charts. Having epics as a first class citizen allows you to quickly pull them in in those scenarios.

changed the description

changed milestone to %10.2

changed the description

added UX label

mentioned in issue #3291

changed the description

added:

Only group members can create epics
Only project members that are also members of the group can promote issues to epics

changed the description

This was part of the original description, but I removed it for now:

There is _no_ epic create web form. Instead, you create an epic by clicking the `New epic` button in the two places (list view and epic view). You enter the title and click `Create epic`. The epic is persisted and you are navigated to the epic.

changed the description

Changed description, going to change it again.. to indicate first iteration and what can be added in later on.

Plus expand further on the idea

@dimitrieh: I don’t see a need to differentiate between open and in progress epics

An epic that is not closed, should just be open. And if you have further information, you could say that an epic is “35% complete”. That solves the use cases of epics for say, in a Gantt chart.

I think we can differentiate between to states/statuses of epics:

Completion of work: I.e. Open vs Complete.
Timeliness of the work: I.e.
- In the past, the epic was Completed on time or Completed late.
- Right now or in the future, the epic is estimated to be On schedule or Will be late

The completion statuses depend on just the issues themselves. So it should not be tied to the epic start/end dates.

The timeliness aspects depend on the end date of the epic, if it is entered.

These are all considering the use cases of the Gantt view and managing a portfolio of projects. So we should think top down, and not consider epics in too much detail yet.

So the progress bar is a strange one, as to what it will need to represent (also see the conversation at https://gitlab.slack.com/archives/C6WA9RWLF/p1505159081000344)

For example, progress can be tracked on open vs closed issues. Another example, perhaps more accurate would be to see how much weight (story points) the closed issues make up for.

However, reality makes clear for us, that none of these factors make to much sense, if all merge requests only get merged (with it closing their issues) at the end of a cycle.

I opened an issue on this: https://gitlab.com/gitlab-org/gitlab-ee/issues/3420

mentioned in issue #3420

@dimitrieh : We need the context and the use cases. What will this be used for? Again, like I said, we should think top down, from the use cases of a single manager looking at Gantt chart, or a team of executives staring at a portfolio view of projects. What do they care about? They will not be looking at a list of epics likely. So I don't think we should focus on the epic specifics first.

mentioned in commit gitlab-design@59f23341

changed the description

@dimitrieh : Let's do the very very bare minimum for epics in this first iteration. And so we can focus on development efforts to get the best roadmap view experience as possible.

See what I put in the description.

changed the description

assigned to @dimitrieh

@victorwu do we want to restrict the following also to only group members?

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.

@dimitrieh : Let's confirm with Sean when he is back next week in terms of permissions. Obviously we don't want to introduce any new permissions model and reuse existing permissions as much as possible.

In what I said there, I was already assuming only group members can manage epics. But let's confirm later.

@victorwu if we have no states for epics, it means we cannot show states for epics that are children of epics... which is a little weird.

Currently I would suggest we fix that with `epic &123 (10/21), where an epic within that epic is also accounted for as 1 children.. and can be considered "completed" when all of its sub issues are closed.

@dimitrieh : Yes please include it in your design, and then we can have a discussion afterward when we need to include it.

For example, we don't care about epics being completed or in progress or not started when we look at the epic view itself. We care only about it when we look at the roadmap view. That is the first use cases we'll consider.

@victorwu @JobV Here is the first real iteration of epics.. which should be implementable. I have taken a lot of cues from issues and issue lists.. as i think a lot can be reused for epics.

There is now also a field in the issue issueable sidebar, which indicates parent (which can only be an epic), similar to the sidebar for the epic. This makes it possible to assign issues from both within the epic, as well as in the issue itself (we can initially start off with asking the user to input the url/id of the epic..similar to how related issues currently work). Apart from that, I reused the epics list and issues list inside the sub issues and sub epics UI box inside an epic. This because this information is probably quite easy to reusable, plus all that information is actually useful to have inside the epic view (i can soon see us expand with a filtering/search option inside that widget as well). Aside from that I tried to keep it as minimalistic as possible.

As to the epics list. I added tabs and search.. as I can see that soon becoming a problem when people actually begin to use it... However if we want to leave it out as a first iteration that is surely possible.

Designs

Epic detail view:

closed issues automatically move to the bottom

Epic list view:

Issue sidebar with room for parent connection:

Looks great @dimitrieh . Just a few comments:

Can you provide the UI for removing an issue/epic from an epic. (Since the design is slightly different from related issues, and I think this is better, we need that UI too.)
Regarding the parent pointer. I don't think we should allow users to change that unless there's a clear use case for it. I think the interaction model is simpler if we only ever assign/remove children. So if you are an epic, you can add/remove your children epic. (And you can steal somebody else's children.) But if you yourself are a child of another epic, you can't "run away" to another parent, or go parent-less. Your parent makes that decision.
Don't you think it's a bit weird to have the parent pointer in the sidebar. All my child issues and child epics are in the center of the screen. So I probably care about my parent in the same context right? So shouldn't it share some locality?
One of the powerful aspects of epics of epics is that you can nesting. So I am sure that would be a feature that's requested to view that hierarchy. Do you think your design here is easily extensible to support that? Similar to the subgroup UI which is essentially a file browser UI. We should account for that in this design, even though we won't implement it right away. I think an easy solution is just to have a modal if you want to see any hierarchy. But is there something better?

Can you provide the UI for removing an issue/epic from an epic. (Since the design is slightly different from related issues, and I think this is better, we need that UI too.)

@victorwu Will do!

Regarding the parent pointer. I don't think we should allow users to change that unless there's a clear use case for it. I think the interaction model is simpler if we only ever assign/remove children. So if you are an epic, you can add/remove your children epic. (And you can steal somebody else's children.) But if you yourself are a child of another epic, you can't "run away" to another parent, or go parent-less. Your parent makes that decision.

Interesting view, however I worry about limiting user interaction here. It feels similar to the reason why we can move an issue from project to project (changing it's.. parent..so to say). I worry that if you see as a user that an issue is assigned to a wrong parent.. you first got to go to the parent.. then fix it.. instead of the other way around. Of course we can just do what you say, and see how people react.. but the fact remains the same with issue project moving

Don't you think it's a bit weird to have the parent pointer in the sidebar. All my child issues and child epics are in the center of the screen. So I probably care about my parent in the same context right? So shouldn't it share some locality?

I think i can give a logical explanation here. The sidebar is for management controls and information, such as milestone, labels, assignees etc.. in short, things that manage the issue. None of these things are managed by the issue. However related issues or the merge request widget are more part of the content of the issue or mr.. therefore deserving a place in the content section.

We could place it above assignee however.

One of the powerful aspects of epics of epics is that you can nesting. So I am sure that would be a feature that's requested to view that hierarchy. Do you think your design here is easily extensible to support that? Similar to the subgroup UI which is essentially a file browser UI. We should account for that in this design, even though we won't implement it right away. I think an easy solution is just to have a modal if you want to see any hierarchy. But is there something better?

Not exactly sure what you are asking for here exactly, but how I had it in mind is that epics rely on groups and subgroups for their hierarchy (they are part of a group, the same as issues are part of a group).

If you want to reveal this information in a visual way though.. which is essentially the pyramid view we talked about in one of our interviews... I would suggest this is, already a bit present in of course the nest-able gantt roadmap view, but in the epics list I could see this working similar to how jira portfolio does this.

They have essentially an extended epics list, which can be expanded to see nested epics and stories (issues in our case):

Will do!

@victorwu see the following design iteration:

Looks good thanks @dimitrieh!

mentioned in commit gitlab-design@b7d0f0f9

mentioned in issue #928 (closed)

changed the description

Why are epics at the group level only? An epic in a project seems like a perfectly valid thing.

What differentiates an epic from a parent issue?

What differentiates an epic from a milestone?

Feels like we’re adding a lot conceptual complexity. I believe users will find this confusing.

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 (https://gitlab.com/gitlab-org/gitlab-ee/issues/3293) 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 (https://gitlab.com/gitlab-org/gitlab-ee/issues/3293), 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.

changed the description

@victorwu Part of the confusion, and I suspect why users are upset that this is EE Ultimate (or at least premium) is that to most users an Epic is simply a type of top-level issue used to track subissues. In JIRA for example, an Epic is a glorified parent issue. Users see that we have related issues so having a simple parent/epic seems a simple thing.

Looking at issue https://gitlab.com/gitlab-org/gitlab-ee/issues/3293, I like where it's going with the roadmap view.

I think perception will ultimately be OK if we explain to users that vanilla issue/subissue relationships will be available in EES and fill the basic role of a meta issue within a project (and it should be EES, not EEP, IMO, but I digress).

Thanks @dblessing . That's a great point. I think we may consider bringing a version of epics that is not targeted at the roadmap feature for EEP or EES.

@smcgivern : Does it make sense to agree on a character to indicate epics now? I assume we will need it later anyways. So we introduce it now? (i.e. similar to # for issues).

Any thoughts? & work?

mentioned in commit gitlab-design@7c27f77f

changed the description

@dimitrieh @sarrahvesselov : @JobV brought up a point about using colors to distinguish the epics page from other similarly looking pages, such as issues. (And of course mrs look the same too.)

I myself personally sometimes get confused if I'm looking at an issue or an mr. Typically I get re-oriented within seconds. But it's still a bit jarring and a sub-par experience. This happens usually when I'm quickly clicking around (say from an email), or I rapidly open multiple tabs and then go through them one by one. I recall @markpundsack may have said this before too. Do we have any issues to discuss this further? We have a chance to introduce something new for epics to have a more distinctive visual style if it makes sense.

I seem to recall someone (probably design team member) saying that the navigation should be the primary tool to help orient a person. But does that mean we can't also use some other visual cue to allow a person to quickly know they are looking at an issue vs an mr vs an epic?

@dimitrieh : I'm closing this issue because I've broken up the work into multiple smaller issues here: https://gitlab.com/gitlab-org/gitlab-ee/issues/3254. We can start scoping out exact designs/deliverables in 10.2 in those issues.

closed

removed milestone

removed the relation with #3254

@victorwu yes, I'm not sure which related issue to comment in, so I'll comment here.

& sounds fine to me - @to1ne provided a helpful list at https://gitlab.com/gitlab-org/gitlab-ce/issues/27508#note_28270490. The wrinkle is that we must 'reserve' this in CE, even though this is an EE-only feature, so that someone doesn't try to add ampersand as a reference prefix in future. I'm not totally sure how to do this yet, but I want to capture that

mentioned in issue #3550

@smcgivern : I've specified (and linked to your comment) in https://gitlab.com/gitlab-org/gitlab-ee/issues/3550's description.

marked this issue as related to #3254

Mockup for 2018 product vision presentation:

mentioned in commit gitlab-design@f83bcd62

mentioned in issue #3665

Epics

Design

Designs

Some questions and responses

Out of scope details

Functionality within an epic

Designs

Child items ...

Activity

Designs

Admin message

Admin message

Epics

Design

Designs

Some questions and responses

Out of scope details

Functionality within an epic

Relates to

Activity

Designs