Skip to content

G
gitlab-ce
Commit 7c9f1195 authored by Russell Dickenson's avatar Russell Dickenson
Browse files
Options

Merge branch 'msj-epics-refresh' into 'master' 

Move Epics instruction docs to a new page

See merge request gitlab-org/gitlab!31634
parents fa7fb00f 2fd93bd4
Show whitespace changes
Inline Side-by-side
Showing with 302 additions and 246 deletions
doc/user/group/epics/index.md
View file @ 7c9f1195
......@@ -11,19 +11,8 @@ Epics let you manage your portfolio of projects more efficiently and with less
effort by tracking groups of issues that share a theme, across projects and
milestones.
## 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). **(ULTIMATE)**
```mermaid
graph TD
Parent_epic --> Issue1
Parent_epic --> Child_epic
Child_epic --> Issue2
```
<!-- Possibly swap this file with one of a single epic -->
![epics list view](img/epics_list_view_v12.5.png)
## Use cases
......@@ -31,76 +20,36 @@ graph TD
- 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.
![epics list view](img/epics_list_view_v12.5.png)
## Creating an epic
A paginated list of epics is available in each group from where you can create
a new epic. The list of epics includes also epics from all subgroups of the
selected group. From your group page:
1. Go to **Epics**.
1. Click **New epic**.
1. Enter a descriptive title and click **Create epic**.
You will be taken to the new epic where can edit the following details:
- Title
- Description
- Start date
- Due date
- Labels
An epic's page contains the following tabs:
- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view.
- Click on the <kbd>></kbd> beside a parent epic to reveal the child epics and issues.
- Hover over the total counts to see a breakdown of open and closed items.
- **Roadmap**: a roadmap view of child epics which have start and due dates.
![epic view](img/epic_view_v13.0.png)
## Adding an issue to an epic
You can add an existing issue to an epic, or, from an epic's page, create a new issue that's automatically added to the epic.
### Adding an existing issue to an epic
## Manage epics
Existing issues that belong to a project in an epic's group, or any of the epic's
subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab.
To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include:
An epic contains a list of issues and an issue can be associated with at most
one epic. When you add an issue that's already linked to an epic,
the issue is automatically unlinked from its current parent.
- [Create an epic](manage_epics.md#create-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)
- [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-ultimate)
To add an issue to an epic:
1. Click the **Add** dropdown button.
1. Click **Add an issue**.
1. Identify the issue to be added, using either of the following methods:
- Paste the link of the issue.
- Search for the desired issue by entering part of the issue's title, then selecting the desired match. ([From GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126))
If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step.
1. Click **Add**.
### Creating an issue from an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7.
Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts.
## Relationships between epics and issues
To create an issue from an epic:
The possible relationships between epics and issues are:
1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select **Create new issue**.
1. Under **Title**, enter the title for the new issue.
1. From the **Project** dropdown, select the project in which the issue should be created.
1. Click **Create issue**.
- 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). **(ULTIMATE)**
To remove an issue from an epic:
```mermaid
graph TD
Parent_epic --> Issue1
Parent_epic --> Child_epic
Child_epic --> Issue2
```
1. Click on the <kbd>x</kbd> button in the epic's issue list.
1. Click **Remove** in the **Remove issue** warning message.
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 issues between epics, or promote an issue to an epic.
## Issue health status in Epic tree **(ULTIMATE)**
......@@ -119,29 +68,15 @@ This feature comes with a feature flag enabled by default. For steps to disable
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8333) in GitLab Ultimate 11.7.
Any epic that belongs to a group, or subgroup of the parent epic's group, is
eligible to be added. New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
Any epic that belongs to a group, or subgroup of the parent epic's group, is eligible to be added.
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.
An epic can have multiple child epics with
the maximum depth being 5.
To add a child epic to an epic:
1. Click the **Add** dropdown button.
1. Click **Add an epic**.
1. Identify the epic to be added, using either of the following methods:
- Paste the link of the epic.
- Search for the desired issue by entering part of the epic's title, then selecting the desired match. ([From GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126))
An epic can have multiple child epics up to the maximum depth of five.
If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step.
1. Click **Add**.
To remove a child epic from a parent epic:
1. Click on the <kbd>x</kbd> button in the parent epic's list of epics.
1. Click **Remove** in the **Remove epic** warning message.
See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics-ultimate) for
steps to create, move, reorder, or delete child epics.
## Start date and due date
......@@ -199,157 +134,6 @@ have a [start or due date](#start-date-and-due-date), a
![Child epics roadmap](img/epic_view_roadmap_v12_9.png)
---
## Reordering issues and child epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
New issues and child epics are added to the top of their respective lists in the **Epics and Issues**
tab. You can reorder the list of issues and the list of child epics. Issues and child epics cannot
be intermingled.
To reorder issues assigned to an epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop issues into the desired order.
To reorder child epics assigned to an epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop epics into the desired order.
## Moving issues and child epics between epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
New issues and child epics are added to the top of their respective lists in the **Epics and Issues**
tab. You can move issues and child epics from one epic to another. Issues and child epics cannot
be intermingled.
To move an issue to another epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop issues into the desired parent epic.
To move child epics to another epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop epics into the desired parent epic.
## Updating epics
### Using bulk editing
To apply labels across multiple epics:
1. Go to the Epics list.
1. Click **Edit epics**.
- Checkboxes will appear beside each epic.
- A sidebar on the right-hand side will appear, with an editable field for labels.
1. Check the checkbox beside each epic to be edited.
1. Select the desired labels.
1. Click **Update all**.
![bulk editing](img/bulk_editing.png)
## Deleting an epic
NOTE: **Note:**
To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup.
When editing the description of an epic, click the **Delete** button to delete the epic.
A modal will pop-up to confirm your action.
Deleting an epic releases all existing issues from their associated epic in the
system.
## Closing and reopening epics
### Using buttons
Whenever you decide that there is no longer need for that epic,
close the epic using the close button:
![close epic - button](img/button_close_epic.png)
You can always reopen it using the reopen button.
![reopen epic - button](img/button_reopen_epic.png)
---
### Using quick actions
You can close or reopen an epic using [Quick actions](../../project/quick_actions.md)
## Navigating to an epic from an issue
If an issue belongs to an epic, you can navigate to the containing epic with the
link in the issue sidebar.
![containing epic](img/containing_epic.png)
---
## Promoting an issue to an epic
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
If you have [permissions](../../permissions.md) to close an issue and create an
epic in the parent group, you can promote an issue to an epic with the `/promote`
[quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
Only issues from projects that are in groups can be promoted. When attempting to promote a confidential
issue, a warning will display. Promoting a confidential issue to an epic will make all information
related to the issue public as epics are public to group members.
When the quick action is executed:
- An epic is created in the same group as the project of the issue.
- Subscribers of the issue are notified that the epic was created.
The following issue metadata will be copied to the epic:
- Title, description, activity/comment thread.
- Upvotes/downvotes.
- Participants.
- Group labels that the issue already has.
## Searching for an epic from epics list page
> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
You can search for an epic from the list of epics using filtered search bar (similar to
that of Issues and Merge Requests) based on following parameters:
- Title or description
- Author name / username
- Labels
![epics search](img/epics_search.png)
To search, go to the list of epics and click on the field **Search or filter results**.
It will display a dropdown menu, from which you can add an author. You can also enter plain
text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
keyboard to filter the list.
You can also sort epics list by:
- Created date
- Last updated
- Start date
- Due date
Each option contains a button that can toggle the order between **Ascending** and **Descending**.
The sort option and order is saved and used wherever you browse epics, including the
[Roadmap](../roadmap/index.md).
![epics sort](img/epics_sort.png)
---
## Permissions
If you have access to view an epic and have access to view an issue already
......
doc/user/group/epics/manage_epics.md 0 → 100644
View file @ 7c9f1195
---
type: howto
---
<!-- When adding a new section here, remember to mention it in index.md#manage-epics -->
# Manage epics **(PREMIUM)**
This page collects instructions for all the things you can do with [epics](index.md) or in relation
to them.
## Create an epic
A paginated list of epics is available in each group from where you can create
a new epic. The list of epics includes also epics from all subgroups of the
selected group. From your group page:
1. Go to **Epics**.
1. Click **New epic**.
1. Enter a descriptive title and click **Create epic**.
You will be taken to the new epic where can edit the following details:
- Title
- Description
- Start date
- Due date
- Labels
An epic's page contains the following tabs:
- **Epics and Issues**: epics and issues added to this epic. Child epics and their issues appear in
a tree view.
- Click the <kbd>></kbd> beside a parent epic to reveal the child epics and issues.
- Hover over the total counts to see a breakdown of open and closed items.
- **Roadmap**: a roadmap view of child epics which have start and due dates.
![epic view](img/epic_view_v13.0.png)
## Bulk-edit epics
You can edit multiple epics at once. For example, to apply labels to multiple epics:
1. Go to the Epics list.
1. Click **Edit epics**.
- Checkboxes appear next to each epic.
- A sidebar on the right-hand side appears with an editable field for labels.
1. Select the checkbox next to each epic to be edited.
1. Select the labels you want.
1. Click **Update all**.
![bulk editing](img/bulk_editing.png)
## Delete an epic
NOTE: **Note:**
To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup.
When editing the description of an epic, click the **Delete** button to delete the epic.
A modal appears to confirm your action.
Deleting an epic releases all existing issues from their associated epic in the system.
## Close an epic
Whenever you decide that there is no longer need for that epic,
close the epic by:
- Clicking the **Close epic** button.
![close epic - button](img/button_close_epic.png)
- Using a [quick action](../../project/quick_actions.md).
## Reopen a closed epic
You can reopen an epic that was closed by:
- Clicking the **Reopen epic** button.
![reopen epic - button](img/button_reopen_epic.png)
- Using a [quick action](../../project/quick_actions.md).
## Go to an epic from an issue
If an issue belongs to an epic, you can navigate to the containing epic with the
link in the issue sidebar.
![containing epic](img/containing_epic.png)
## Search for an epic from epics list page
> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/37081) to the [Premium](https://about.gitlab.com/pricing/) tier in GitLab 12.8.
You can search for an epic from the list of epics using filtered search bar (similar to
that of Issues and Merge Requests) based on following parameters:
- Title or description
- Author name / username
- Labels
![epics search](img/epics_search.png)
To search, go to the list of epics and click the field **Search or filter results**.
It will display a dropdown menu, from which you can add an author. You can also enter plain
text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
keyboard to filter the list.
You can also sort epics list by:
- Created date
- Last updated
- Start date
- Due date
Each option contains a button that can toggle the order between **Ascending** and **Descending**.
The sort option and order is saved and used wherever you browse epics, including the
[Roadmap](../roadmap/index.md).
![epics sort](img/epics_sort.png)
## Manage issues assigned to an epic
### Add an issue to an epic
You can add an existing issue to an epic, or, create a new issue that's
automatically added to the epic.
#### Add an existing issue to an epic
Existing issues that belong to a project in an epic's group, or any of the epic's
subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of
issues in the **Epics and Issues** tab.
An epic contains a list of issues and an issue can be associated with at most one epic.
When you add an issue that's already linked to an epic, the issue is automatically unlinked from its
current parent.
To add an issue to an epic:
1. Click the **Add** dropdown button.
1. Click **Add an issue**.
1. Identify the issue to be added, using either of the following methods:
- Paste the link of the issue.
- Search for the desired issue by entering part of the issue's title, then selecting the desired
match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)).
If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step.
1. Click **Add**.
#### Create an issue from an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7.
Creating an issue from an epic enables you to maintain focus on the broader context of the epic
while dividing work into smaller parts.
To create an issue from an epic:
1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select
**Create new issue**.
1. Under **Title**, enter the title for the new issue.
1. From the **Project** dropdown, select the project in which the issue should be created.
1. Click **Create issue**.
To remove an issue from an epic:
1. Click the <kbd>x</kbd> button in the epic's issue list.
1. Click **Remove** in the **Remove issue** warning message.
### Reorder issues assigned to an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
New issues are added to the top of their list in the **Epics and Issues** tab.
You can reorder the list of issues. Issues and child epics cannot be intermingled.
To reorder issues assigned to an epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop issues into the desired order.
To reorder child epics assigned to an epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop epics into the desired order.
### Move issues between epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
New issues are added to the top of their list in the **Epics and Issues**
tab. You can move issues from one epic to another. Issues and child epics cannot be intermingled.
To move an issue to another epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop issues into the desired parent epic.
### Promote an issue to an epic
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
If you have [permissions](../../permissions.md) to close an issue and create an
epic in the parent group, you can promote an issue to an epic with the `/promote`
[quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
Only issues from projects that are in groups can be promoted. When attempting to promote a confidential
issue, a warning will display. Promoting a confidential issue to an epic will make all information
related to the issue public as epics are public to group members.
When the quick action is executed:
- An epic is created in the same group as the project of the issue.
- Subscribers of the issue are notified that the epic was created.
The following issue metadata will be copied to the epic:
- Title, description, activity/comment thread.
- Upvotes/downvotes.
- Participants.
- Group labels that the issue already has.
## Manage multi-level child epics **(ULTIMATE)**
### Add a child epic to an epic
To add a child epic to an epic:
1. Click the **Add** dropdown button.
1. Click **Add an epic**.
1. Identify the epic to be added, using either of the following methods:
- Paste the link of the epic.
- Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)).
If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step.
1. Click **Add**.
### Move child epics between epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
New child epics are added to the top of their list in the **Epics and Issues** tab.
You can move child epics from one epic to another.
When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
Issues and child epics cannot be intermingled.
To move child epics **(ULTIMATE)** to another epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop epics into the desired parent epic.
### Reorder child epics assigned to an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
New child epics are added to the top of their list in the **Epics and Issues** tab.
You can reorder the list of child epics. Issues and child epics cannot be intermingled.
To reorder child epics assigned to an epic:
1. Go to the **Epics and Issues** tab.
1. Drag and drop epics into the desired order.
### Remove a child epic from a parent epic
To remove a child epic from a parent epic:
1. Click on the <kbd>x</kbd> button in the parent epic's list of epics.
1. Click **Remove** in the **Remove epic** warning message.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7