diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 15:44:42 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 15:44:42 +0000 |
commit | 4555e1b21c365ed8303ffb7a3325d773c9b8bf31 (patch) | |
tree | 5423a1c7516cffe36384133ade12572cf709398d /doc/user/group/epics | |
parent | e570267f2f6b326480d284e0164a6464ba4081bc (diff) | |
download | gitlab-ce-4555e1b21c365ed8303ffb7a3325d773c9b8bf31.tar.gz |
Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42
Diffstat (limited to 'doc/user/group/epics')
-rw-r--r-- | doc/user/group/epics/img/epic_board_v13_10.png | bin | 60672 -> 42037 bytes | |||
-rw-r--r-- | doc/user/group/epics/img/epic_view_roadmap_v12_9.png | bin | 127201 -> 105562 bytes | |||
-rw-r--r-- | doc/user/group/epics/img/epic_view_v13.0.png | bin | 54891 -> 0 bytes | |||
-rw-r--r-- | doc/user/group/epics/img/new_epic_from_groups_v13.7.png | bin | 10505 -> 0 bytes | |||
-rw-r--r-- | doc/user/group/epics/index.md | 157 | ||||
-rw-r--r-- | doc/user/group/epics/manage_epics.md | 90 |
6 files changed, 95 insertions, 152 deletions
diff --git a/doc/user/group/epics/img/epic_board_v13_10.png b/doc/user/group/epics/img/epic_board_v13_10.png Binary files differindex 5a14d9288d3..85a131ea605 100644 --- a/doc/user/group/epics/img/epic_board_v13_10.png +++ b/doc/user/group/epics/img/epic_board_v13_10.png diff --git a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png Binary files differindex 035adc5e7ac..e8224ced7e9 100644 --- a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png +++ b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png diff --git a/doc/user/group/epics/img/epic_view_v13.0.png b/doc/user/group/epics/img/epic_view_v13.0.png Binary files differdeleted file mode 100644 index b25a91d318a..00000000000 --- a/doc/user/group/epics/img/epic_view_v13.0.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png Binary files differdeleted file mode 100644 index 3607d5c7a3f..00000000000 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png +++ /dev/null diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 12377b3926d..0608ff38db1 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -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](../bulk_editing/index.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. - -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 up to the maximum depth of seven. - -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 diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 1999e5ba214..7bb021b4b1f 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -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,15 +73,26 @@ 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. -## Bulk-edit epics +## Bulk edit epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -You can edit multiple epics at once. To learn how to do it, visit -[Bulk editing issues, epics, and merge requests at the group level](../bulk_editing/index.md#bulk-edit-epics). +Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. + +When bulk editing epics in a group, you can edit their labels. + +To update multiple epics at the same time: + +1. In a group, go to **Epics > List**. +1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Check the checkboxes next to each epic you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. ## Delete an epic @@ -140,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. @@ -162,6 +204,13 @@ To make an epic confidential: This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) in relation to epics. +### 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. + ### Add a new issue to an epic You can add an existing issue to an epic, or create a new issue that's @@ -275,7 +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. + +Epics can contain multiple nested child epics, up to a total of seven levels deep. ### Add a child epic to an epic |