Merge branch '290039-epic-boards-docs-14-0' into 'master'

Epic boards docs update for 14.0 release

See merge request gitlab-org/gitlab!62434

doc/user/group/epics/epic_boards.md

@@ -6,17 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Epic Boards **(PREMIUM)**
 
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2864) in GitLab 13.10.
-> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
-> - It's disabled on GitLab.com.
-> - It's not recommended for production use.
-> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../administration/feature_flags.md).
-
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
-The GitLab Epic Board is a software project management tool used to plan,
-organize, and visualize a workflow for a feature or product release.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10.
+> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default.
+> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.0.
+> - Enabled on GitLab.com.
+> - Recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/feature_flags.md).
 
 Epic boards build on the existing [epic tracking functionality](index.md) and
 [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned
@@ -24,45 +19,156 @@ labels.
 
 To view an epic board, in a group, select **Epics > Boards**.
 
-![GitLab epic board - Premium](img/epic_board_v13_10.png)
+![GitLab epic board - Premium](img/epic_board_v14_0.png)
 
 ## Create an epic board
 
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+
 To create a new epic board:
 
-1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page.
+1. Go to your group and select **Epics > Boards**.
+1. In the upper left corner, select the dropdown with the current board name.
 1. Select **Create new board**.
-1. Enter the new board's name and select **Create**.
+1. Enter the new board's title.
+1. Optional. To hide the Open or Closed lists, clear the **Show the Open list** and
+   **Show the Closed list** checkboxes.
+1. Optional. Set board scope:
+   1. Next to **Scope**, select **Expand**.
+   1. Next to **Labels**, select **Edit** and select the labels to use as board scope.
+1. Select **Create board**.
+
+Now you can [add some lists](#create-a-new-list).
+To change these options later, [edit the board](#edit-the-scope-of-an-epic-board).
+
+## Delete an epic board
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0.
+
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+- A minimum of two boards present in a group.
+
+To delete the active epic board:
+
+1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page.
+1. Select **Delete board**.
+1. Select **Delete**.
+
+## Actions you can take on an epic board
+
+- [Create a new list](#create-a-new-list).
+- [Remove an existing list](#remove-a-list).
+- [Filter epics](#filter-epics).
+- Create workflows, like when using [issue boards](../../project/issue_board.md#create-workflows).
+- [Move epics and lists](#move-epics-and-lists).
+- Change epic labels (by dragging an epic between lists).
+- Close an epic (by dragging it to the **Closed** list).
+- [Edit the scope of a board](#edit-the-scope-of-an-epic-board).
+
+### Create a new list
+
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+
+To create a new list:
+
+1. Go to your group and select **Epics > Boards**.
+1. In the upper-right corner, select **Create list**.
+1. In the **New list** column expand the **Select a label** dropdown and select the label to use as
+   list scope.
+1. Select **Add to board**.
+
+### Remove a list
+
+Removing a list doesn't have any effect on epics and labels, as it's just the
+list view that's removed. You can always create it again later if you need.
+
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+
+To remove a list from an epic board:
 
-## Limitations of epic boards
+1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**).
+   The list settings sidebar opens on the right.
+1. Select **Remove list**. A confirmation dialog appears.
+1. Select **OK**.
 
-As of GitLab 13.10, these limitations apply:
+### Filter epics
 
-- Epic Boards need to be enabled by an administrator.
-- Epic Boards can be created but not deleted.
-- Lists can be added to the board but not deleted.
-- There is no sidebar on the board. To edit an epic, go to the epic's page.
-- There is no drag and drop support yet. To move an epic between lists, edit epic labels on the epic's page.
-- Epics cannot be re-ordered within the list.
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0.
 
-To learn more about the future iterations of this feature, visit
-[epic 5067](https://gitlab.com/groups/gitlab-org/-/epics/5067).
+Use the filters on top of your epic board to show only
+the results you want. It's similar to the filtering used in the epic list,
+as the metadata from the epics and labels is re-used in the epic board.
 
-## Enable or disable Epic Boards
+You can filter by the following:
 
-Epic Boards are under development and not ready for production use. It is
-deployed behind a feature flag that is **disabled by default**.
+- Author
+- Label
+
+### Move epics and lists
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0.
+
+You can move epics and lists by dragging them.
+
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+
+To move an epic, select the epic card and drag it to another position in its current list or
+into another list. Learn about possible effects in [Dragging epics between lists](#dragging-epics-between-lists).
+
+To move a list, select its top bar, and drag it horizontally.
+You can't move the **Open** and **Closed** lists, but you can hide them when editing an epic board.
+
+#### Dragging epics between lists
+
+When you drag epics between lists, the result is different depending on the source list
+and the target list.
+
+|                       | To Open        | To Closed  | To label B list                |
+| --------------------- | -------------- | ---------- | ------------------------------ |
+| **From Open**         | -              | Close epic | Add label B                    |
+| **From Closed**       | Reopen epic    | -          | Reopen epic and add label B    |
+| **From label A list** | Remove label A | Close epic | Remove label A and add label B |
+
+### Edit the scope of an epic board
+
+Prerequisites:
+
+- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab.
+
+To edit the scope of an epic board:
+
+1. In the upper-right corner, select **Edit board**.
+1. Optional:
+   - Edit the board's title.
+   - Show or hide the Open and Closed columns.
+   - Select other labels as the board's scope.
+1. Select **Save changes**.
+
+## Enable or disable epic boards
+
+Epic boards are under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
 [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
-can enable it.
+can disable it.
 
-To enable it:
+To disable it:
 
 ```ruby
-Feature.enable(:epic_boards)
+Feature.disable(:epic_boards)
 ```
 
-To disable it:
+To enable it:
 
 ```ruby
-Feature.disable(:epic_boards)
+Feature.enable(:epic_boards)
 ```

doc/user/permissions.md

@@ -263,8 +263,9 @@ The following table lists group permissions available for each role:
 | Browse group                                           | ✓     | ✓        | ✓         | ✓          | ✓     |
 | View group wiki pages **(PREMIUM)**                    | ✓ (6) | ✓        | ✓         | ✓          | ✓     |
 | View Insights charts **(ULTIMATE)**                    | ✓     | ✓        | ✓         | ✓          | ✓     |
-| View group epic **(PREMIUM)**                         | ✓     | ✓        | ✓         | ✓          | ✓     |
-| Create/edit group epic **(PREMIUM)**                  |       | ✓        | ✓         | ✓          | ✓     |
+| View group epic **(PREMIUM)**                          | ✓     | ✓        | ✓         | ✓          | ✓     |
+| Create/edit group epic **(PREMIUM)**                   |       | ✓        | ✓         | ✓          | ✓     |
+| Create/edit/delete epic boards **(PREMIUM)**           |       | ✓        | ✓         | ✓          | ✓     |
 | Manage group labels                                    |       | ✓        | ✓         | ✓          | ✓     |
 | See a container registry                               |       | ✓        | ✓         | ✓          | ✓     |
 | Pull [packages](packages/index.md)                     |       | ✓        | ✓         | ✓          | ✓     |
@@ -288,8 +289,8 @@ The following table lists group permissions available for each role:
 | Create/Delete group deploy tokens                      |       |          |           |            | ✓     |
 | Manage group members                                   |       |          |           |            | ✓     |
 | Delete group                                           |       |          |           |            | ✓     |
-| Delete group epic **(PREMIUM)**                       |       |          |           |            | ✓     |
-| Edit SAML SSO Billing **(PREMIUM SAAS)**                | ✓     | ✓        | ✓         | ✓          | ✓ (4) |
+| Delete group epic **(PREMIUM)**                        |       |          |           |            | ✓     |
+| Edit SAML SSO Billing **(PREMIUM SAAS)**               | ✓     | ✓        | ✓         | ✓          | ✓ (4) |
 | View group Audit Events                                |       |          | ✓ (7)     | ✓ (7)      | ✓     |
 | Disable notification emails                            |       |          |           |            | ✓     |
 | View Contribution analytics                            | ✓     | ✓        | ✓         | ✓          | ✓     |

doc/user/project/issue_board.md

@@ -34,11 +34,11 @@ boards in the same project.
 Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/),
 as shown in the following table:
 
-| Tier             | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) |
-|------------------|--------------------------------|------------------------------|---------------------------|----------------|
-| Free             | Multiple                       | 1                            | No                        | No             |
-| Premium          | Multiple                       | Multiple                     | Yes                       | Yes            |
-| Ultimate         | Multiple                       | Multiple                     | Yes                       | Yes            |
+| Tier     | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) |
+| -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- |
+| Free     | Multiple                       | 1                                                   | No                                                      | No                                |
+| Premium  | Multiple                       | Multiple                                            | Yes                                                     | Yes                               |
+| Ultimate | Multiple                       | Multiple                                            | Yes                                                     | Yes                               |
 
 To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below.
 
@@ -312,7 +312,7 @@ assignee list:
 1. Search and select the user you want to add as an assignee.
 
 Now that the assignee list is added, you can assign or unassign issues to that user
-by [dragging issues](#drag-issues-between-lists) to and from an assignee list.
+by [moving issues](#move-issues-and-lists) to and from an assignee list.
 To remove an assignee list, just as with a label list, click the trash icon.
 
 ![Assignee lists](img/issue_board_assignee_lists_v13_6.png)
@@ -328,7 +328,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m
 1. Select the **Milestone** tab.
 1. Search and click the milestone.
 
-Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists)
+Like the assignee lists, you're able to [drag issues](#move-issues-and-lists)
 to and from a milestone list to manipulate the milestone of the dragged issues.
 As in other list types, click the trash icon to remove a list.
 
@@ -355,7 +355,7 @@ iteration. To add an iteration list:
 1. In the dropdown, select an iteration.
 1. Select **Add to board**.
 
-Like the milestone lists, you're able to [drag issues](#drag-issues-between-lists)
+Like the milestone lists, you're able to [drag issues](#move-issues-and-lists)
 to and from a iteration list to manipulate the iteration of the dragged issues.
 
 ![Iteration lists](img/issue_board_iteration_lists_v13_10.png)
@@ -380,7 +380,20 @@ To group issues by epic in an issue board:
 
 ![Epics Swimlanes](img/epics_swimlanes_v13.6.png)
 
-You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment:
+To edit an issue without leaving this view, select the issue card (not its title), and a sidebar
+appears on the right. There you can see and edit the issue's:
+
+- Title
+- Assignees
+- Epic **PREMIUM**
+- Milestone
+- Time tracking value (view only)
+- Due date
+- Labels
+- Weight
+- Notifications setting
+
+You can also [drag issues](#move-issues-and-lists) to change their position and epic assignment:
 
 - To reorder an issue, drag it to the new position within a list.
 - To assign an issue to another epic, drag it to the epic's horizontal lane.
@@ -435,11 +448,11 @@ This feature is only supported when using the [GraphQL-based boards](#graphql-ba
 - [Remove an issue from a list](#remove-an-issue-from-a-list).
 - [Filter issues](#filter-issues) that appear across your issue board.
 - [Create workflows](#create-workflows).
-- [Drag issues between lists](#drag-issues-between-lists).
+- [Move issues and lists](#move-issues-and-lists).
 - [Multi-select issue cards](#multi-select-issue-cards).
 - Drag and reorder the lists.
 - Change issue labels (by dragging an issue between lists).
-- Close an issue (by dragging it to the **Done** list).
+- Close an issue (by dragging it to the **Closed** list).
 
 If you're not able to do some of the things above, make sure you have the right
 [permissions](#permissions).
@@ -483,12 +496,12 @@ You can now choose it to create a list.
 ### Remove a list
 
 Removing a list doesn't have any effect on issues and labels, as it's just the
-list view that's removed. You can always restore it later if you need.
+list view that's removed. You can always create it again later if you need.
 
 To remove a list from an issue board:
 
-1. Select the **List settings** icon (**{settings}**) on the top of the list you want to remove. The
-   list settings sidebar opens on the right.
+1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**).
+   The list settings sidebar opens on the right.
 1. Select **Remove list**. A confirmation dialog appears.
 1. Select **OK**.
 
@@ -582,16 +595,33 @@ to another list, the label changes and a system note is recorded.
 
 ![issue board system notes](img/issue_board_system_notes_v13_6.png)
 
-### Drag issues between lists
+### Move issues and lists
+
+You can move issues and lists by dragging them.
+
+Prerequisites:
+
+- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab.
+
+To move an issue, select the issue card and drag it to another position in its current list or
+into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists).
+
+To move a list, select its top bar, and drag it horizontally.
+You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board.
+
+#### Dragging issues between lists
+
+To move an issue to another list, select the issue card and drag it onto that list.
 
-When dragging issues between lists, different behavior occurs depending on the source list and the target list.
+When you drag issues between lists, the result is different depending on the source list
+and the target list.
 
-|                                | To Open            | To Closed    | To label `B` list            | To assignee `Bob` list                |
-| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- |
-| **From Open**                  | -                  | Issue closed | `B` added                    | `Bob` assigned                        |
-| **From Closed**                | Issue reopened     | -            | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned     |
-| **From label `A` list**        | `A` removed        | Issue closed | `A` removed<br/>`B` added    | `Bob` assigned                        |
-| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added                    | `Alice` unassigned<br/>`Bob` assigned |
+|                              | To Open        | To Closed   | To label B list                | To assignee Bob list          |
+| ---------------------------- | -------------- | ----------- | ------------------------------ | ----------------------------- |
+| **From Open**                | -              | Close issue | Add label B                    | Assign Bob                    |
+| **From Closed**              | Reopen issue   | -           | Reopen issue and add label B   | Reopen issue and assign Bob   |
+| **From label A list**        | Remove label A | Close issue | Remove label A and add label B | Assign Bob                    |
+| **From assignee Alice list** | Unassign Alice | Close issue | Add label B                    | Unassign Alice and assign Bob |
 
 ### Multi-select issue cards