diff options
Diffstat (limited to 'doc/user/group/epics/manage_epics.md')
| -rw-r--r-- | doc/user/group/epics/manage_epics.md | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md new file mode 100644 index 00000000000..8e2a47bb1af --- /dev/null +++ b/doc/user/group/epics/manage_epics.md @@ -0,0 +1,272 @@ +--- +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. + + + +## 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**. + + + +## 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. + +  + +- 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. + +  + +- 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. + + + +## 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 + + + +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). + + + +## 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. |