Commit 041f3a46 authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski

Merge branch 'selhorn-docs-epics-1' into 'master'

Edited Epics topic for CTRT

See merge request gitlab-org/gitlab!61303
parents 44c58cd6 2bce583f
......@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9188) in GitLab 11.8.
Manages parent-child [epic relationships](../user/group/epics/index.md#multi-level-child-epics).
Manages parent-child [epic relationships](../user/group/epics/manage_epics.md#multi-level-child-epics).
Every API call to `epic_links` must be authenticated.
......
......@@ -8,57 +8,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Epics **(PREMIUM)**
> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2.
> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
> - Single-level epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md)
that share a theme across projects and milestones.
When [issues](../../project/issues/index.md) share a theme across projects and milestones,
you can manage them by using epics.
An epic's page contains the following tabs:
You can also create child epics, and assign start and end dates,
which creates a visual roadmap for you to view progress.
- **Issues**: issues added to this epic.
- **Epics and Issues**: epics and issues added to this epic.
Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics).
Child epics and their issues are shown in a tree view.
Use epics:
- To reveal the child epics and issues, select the chevron (**>**) next to a parent epic.
- To see a breakdown of open and closed items, hover over the total counts.
The number provided here includes all epics associated with this project. The number includes
epics for which users may not yet have permission.
- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates.
Appears if you have access to [multi-level epics](#multi-level-child-epics).
![epic view](img/epic_view_v13.0.png)
## Use cases
- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature.
- Track when the work for the group of issues is targeted to begin, and when it's targeted to end.
- Discuss and collaborate on feature ideas and scope at a high level.
## Manage epics
To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include:
- [Create an epic](manage_epics.md#create-an-epic)
- [Edit an epic](manage_epics.md#edit-an-epic)
- [Bulk-edit epics](manage_epics.md#bulk-edit-epics)
- [Delete an epic](manage_epics.md#delete-an-epic)
- [Close an epic](manage_epics.md#close-an-epic)
- [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic)
- [Go to an epic from an issue](manage_epics.md#go-to-an-epic-from-an-issue)
- [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page)
- [Make an epic confidential](manage_epics.md#make-an-epic-confidential)
- [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic)
- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics)
- When your team is working on a large feature that involves multiple discussions
in different issues in different projects in a [group](../index.md).
- To track when the work for the group of issues is targeted to begin and end.
- To discuss and collaborate on feature ideas and scope at a high level.
## Relationships between epics and issues
The possible relationships between epics and issues are:
- An epic is the parent of one or more issues.
- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics). **(ULTIMATE)**
- An epic is the parent of one or more child epics. For details see [Multi-level child epics](manage_epics.md#multi-level-child-epics).
```mermaid
graph TD
......@@ -67,72 +37,13 @@ graph TD
Child_epic --> Issue2
```
See [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) for steps
to:
- Add an issue to an epic
- Reorder issues
- Move an issue between epics
- Promote an issue to an epic
## Issue health status in Epic tree **(ULTIMATE)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10.
> - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7.
Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/managing_issues.md#health-status), which then appears on your Epic tree.
## Multi-level child epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
You can add any epic that belongs to a group or subgroup of the parent epic's group.
New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
Epics can contain multiple nested child epics, up to a total of seven levels deep.
See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for
steps to create, move, reorder, or delete child epics.
## Start date and due date
To set a **Start date** and **Due date** for an epic, select one of the following:
- **Fixed**: enter a fixed value.
- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones.
### Inherited
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
If you select **Inherited**:
- For the **start date**: GitLab scans all child epics and issues assigned to the epic,
and sets the start date to match the earliest found start date or milestone.
- For the **due date**: GitLab sets the due date to match the latest due date or
milestone found among its child epics and issues.
These are dynamic dates and recalculated if any of the following occur:
- A child epic's dates change.
- Milestones are reassigned to an issue.
- A milestone's dates change.
- Issues are added to, or removed from, the epic.
Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top.
If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic.
The parent epic's start date then reflects this change and propagates upwards to the top epic.
## Roadmap in epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10.
If your epic contains one or more [child epics](#multi-level-child-epics) which
have a [start or due date](#start-date-and-due-date), a
[roadmap](../roadmap/index.md) view of the child epics is listed under the parent epic.
If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that
have a start or due date, a visual
[roadmap](../roadmap/index.md) of the child epics is listed under the parent epic.
![Child epics roadmap](img/epic_view_roadmap_v12_9.png)
......@@ -144,45 +55,19 @@ epic's issue list.
If you have access to edit an epic and an issue added to that epic, you can add the issue to or
remove it from the epic.
Note that for a given group, the visibility of all projects must be the same as
For a given group, the visibility of all projects must be the same as
the group, or less restrictive. That means if you have access to a group's epic,
then you already have access to its projects' issues.
You can also consult the [group permissions table](../../permissions.md#group-members-permissions).
## Thread
- Comments: collaborate on that epic by posting comments in its thread.
These text fields also fully support
[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown).
## Comment or start a thread
Once you write your comment, you can either:
- Click **Comment** to publish your comment.
- Click **Start thread** to start a thread within that epic's discussion.
### Activity sort order
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
You can reverse the default order and interact with the activity feed sorted by most recent items
at the top. Your preference is saved via local storage and automatically applied to every issue
you view.
To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest
or newest items to be shown first.
![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png)
## Award emoji
You can [award an emoji](../../award_emojis.md) to that epic or its comments.
## Notifications
## Related topics
You can [turn on notifications](../../profile/notifications.md) to be alerted about epic events.
- [Manage epics](manage_epics.md) and multi-level child epics.
- [Turn on notifications](../../profile/notifications.md) for about epic events.
- [Award an emoji](../../award_emojis.md) to an epic or its comments.
- Collaborate on an epic by posting comments in a [thread](../../discussions/index.md).
- Use [health status](../../project/issues/managing_issues.md#health-status) to track your progress.
<!-- ## Troubleshooting
......
......@@ -16,28 +16,46 @@ to them.
> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
> - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form.
> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty Roadmap.
> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap.
To create an epic in the group you're in:
1. Get to the New Epic form:
- From the **Epics** list in your group, select **New epic**.
- Go to your group and from the left sidebar select **Epics**. Then select **New epic**.
- From an epic in your group, select **New epic**.
- From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**.
- In an empty [roadmap](../roadmap/index.md), select **New epic**.
![New epic from an open epic](img/new_epic_from_groups_v13.7.png)
1. Enter a title.
1. Optional. Enter a description.
1. Optional. To make the epic confidential, select the [Confidentiality checkbox](#make-an-epic-confidential).
1. Optional. Choose labels.
1. Optional. Select a start and due date, or [inherit](#start-and-due-date-inheritance) them.
1. Select **Create epic**.
1. Fill in these fields:
The newly created epic opens.
- Title
- Description
- [Confidentiality checkbox](#make-an-epic-confidential)
- Labels
- Start date
- Due date
### Start and due date inheritance
1. Select **Create epic**. You are taken to view the newly created epic.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
If you select **Inherited**:
- For the **start date**: GitLab scans all child epics and issues assigned to the epic,
and sets the start date to match the earliest found start date or milestone.
- For the **due date**: GitLab sets the due date to match the latest due date or
milestone found among its child epics and issues.
These are dynamic dates and recalculated if any of the following occur:
- A child epic's dates change.
- Milestones are reassigned to an issue.
- A milestone's dates change.
- Issues are added to, or removed from, the epic.
Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top.
If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic.
The parent epic's start date then reflects this change and propagates upwards to the top epic.
## Edit an epic
......@@ -55,7 +73,7 @@ To edit an epic's title or description:
1. Make your changes.
1. Select **Save changes**.
To edit an epics' start date, due date, or labels:
To edit an epic's start date, due date, or labels:
1. Select **Edit** next to each section in the epic sidebar.
1. Select the dates or labels for your epic.
......@@ -151,6 +169,19 @@ The sort option and order is saved and used wherever you browse epics, including
![epics sort](img/epics_sort.png)
## Change activity sort order
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
You can reverse the default order and interact with the activity feed sorted by most recent items
at the top. Your preference is saved via local storage and automatically applied to every epic and issue
you view.
To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest
or newest items to be shown first.
![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png)
## Make an epic confidential
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0 behind a feature flag, disabled by default.
......@@ -200,6 +231,13 @@ To add a new issue to an epic:
If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step.
1. Select **Add**.
#### View count of issues in an epic
On the **Epics and Issues** tab, under each epic name, hover over the total counts.
The number indicates all epics associated with the project, including issues
you might not have permission to.
#### Create an issue from an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7.
......@@ -286,9 +324,16 @@ For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](
For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/).
## Manage multi-level child epics **(ULTIMATE)**
## Multi-level child epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
You can add any epic that belongs to a group or subgroup of the parent epic's group.
New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
With [multi-level epics](index.md#multi-level-child-epics), you can manage more complex projects.
Epics can contain multiple nested child epics, up to a total of seven levels deep.
### Add a child epic to an epic
......
......@@ -62,7 +62,7 @@ When you're creating a new issue, these are the fields you can fill in:
- Checkbox to make the issue confidential
- Assignee
- Weight
- Epic **(PREMIUM)**
- [Epic](../../group/epics/index.md)
- Due date
- Milestone
- Labels
......@@ -402,5 +402,4 @@ This marks issues as progressing as planned or needs attention to keep on schedu
After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled
until the issue is reopened.
You can then see issue statuses in the issues list and the
[epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree).
You can then see issue statuses in the issues list and the epic tree.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment