diff options
Diffstat (limited to 'doc/user/group/epics/index.md')
| -rw-r--r-- | doc/user/group/epics/index.md | 257 |
1 files changed, 32 insertions, 225 deletions
diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 024f346ad47..d53acaf502a 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -5,25 +5,14 @@ type: reference, howto # Epics **(PREMIUM)** > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. -> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), single-level Epics were moved to the Premium tier. +> - 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 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 --> + ## Use cases @@ -31,75 +20,37 @@ 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. - - -## 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. - - - -## 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. +## Manage epics -### Adding an existing issue to an epic +To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include: -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. +- [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) +- [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-ultimate) -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 **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 arrow next to **Add an issue** 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)** @@ -118,28 +69,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 **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 @@ -197,137 +135,6 @@ have a [start or due date](#start-date-and-due-date), a  ---- - -## 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. - -## 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**. - - - -## 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 inside a single epic view, 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: - - - -You can always reopen it using the reopen button. - - - ---- - -### 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. - - - ---- - -## 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 - - - -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). - - - ---- - ## Permissions If you have access to view an epic and have access to view an issue already |