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

Move Epics instruction docs to a new page

See merge request gitlab-org/gitlab!31634

doc/user/group/epics/manage_epics.md

+---
+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.