diff options
Diffstat (limited to 'doc/user/project/issue_board.md')
| -rw-r--r-- | doc/user/project/issue_board.md | 199 |
1 files changed, 136 insertions, 63 deletions
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e1b6956f873..8f71d469e34 100644 --- a/doc/user/project/issue_board.md +++ b/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. @@ -203,7 +203,7 @@ When visiting a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions. -The first time a given issue appears in any board (that is, the first time a user +The first time an issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list. The order is done according to [label priority](labels.md#label-priority). @@ -222,6 +222,28 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. +### GraphQL-based issue boards + +<!-- This anchor is linked from #blocked-issues as well. --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +The work-in-progress GraphQL-based boards come with these features: + +- [Edit more issue attributes](#edit-an-issue) +- [View blocked issues](#blocked-issues) + +The GraphQL-based Issue Board is a work in progress. +Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -269,40 +291,12 @@ especially in combination with [assignee lists](#assignee-lists).  -### Group issue boards **(PREMIUM)** +### Group issue boards Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -#### GraphQL-based sidebar for group issue boards **(PREMIUM)** - -<!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> -<!-- This anchor is linked from #blocked-issues as well. --> - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - 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](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the -ability to edit issue titles in the issue sidebar. - -To **edit an issue's title** in the issue sidebar: - -1. In a group issue board, select the issue card. The issue sidebar opens on the right. -1. Next to the issue's title, select **Edit**. +It can display issues from all projects that fall under the group and its descendant subgroups. -This is work in progress as of GitLab 13.9. Learn more about the known issues in -[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). - -<!-- Add this at the end of the file --> +Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** @@ -318,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.  @@ -334,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. @@ -361,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.  @@ -399,7 +393,7 @@ appears on the right. There you can see and edit the issue's: - Weight - Notifications setting -You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: +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. @@ -442,27 +436,49 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -To enable this in group issue boards, enable the [GraphQL-based sidebar](#graphql-based-sidebar-for-group-issue-boards). -The feature is enabled by default when you use group issue boards with epic swimlanes. +This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode.  ## Actions you can take on an issue board +- [Edit an issue](#edit-an-issue). - [Create a new list](#create-a-new-list). - [Remove an existing list](#remove-a-list). - [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). +### Edit an issue + +You can edit an issue without leaving the board view. +To open the right sidebar, select an issue card (not its title). + +You can edit the following issue attributes in the right sidebar: + +- Assignees +- [Epic](../group/epics/index.md) +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- [Weight](issues/issue_weight.md) +- Notifications setting + +When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: + +- Title +- [Iteration](../group/iterations/index.md) +- Confidentiality + ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -480,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**. @@ -516,9 +532,8 @@ The steps depend on the scope of the list: ### Filter issues -You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker, -as the metadata from the issues and labels is re-used in the issue board. +You can use the filters on top of your issue board to show only +the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). You can filter by the following: @@ -532,6 +547,16 @@ You can filter by the following: - Release - Weight +#### Filtering issues in a group board + +When [filtering issues](#filter-issues) in a **group** board, keep this behavior in mind: + +- Milestones: you can filter by the milestones belonging to the group and its descendant groups. +- Labels: you can only filter by the labels belonging to the group but not its descendant groups. + +When you edit issues individually using the right sidebar, you can additionally select the +milestones and labels from the **project** that the issue is from. + ### Create workflows By reordering your lists, you can create workflows. As lists in issue boards are @@ -570,20 +595,45 @@ to another list, the label changes and a system note is recorded.  -### Drag issues between lists +### Move issues and lists + +You can move issues and lists by dragging them. + +Prerequisites: -When dragging issues between lists, different behavior occurs depending on the source list and the target list. +- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. -| | 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 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 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** | - | 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 -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -626,10 +676,14 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -## Enable or disable GraphQL-based sidebar for group issue boards **(PREMIUM SELF)** +### Enable or disable GraphQL-based issue boards **(FREE SELF)** -GraphQL-based sidebar for group issue boards is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +NOTE: +When enabling GraphQL-based issue boards, you must also enable the +[new add list form](#enable-or-disable-new-add-list-form). + +GraphQL-based issue boards is not ready for production use. +It is deployed behind a feature flag that is **disabled by default** as of GitLab 13.12. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. @@ -685,3 +739,22 @@ To disable it: ```ruby Feature.disable(:iteration_board_lists) ``` + +### Enable or disable multi-selecting issue cards **(FREE SELF)** + +Multi-selecting issue cards is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:board_multi_select) +``` + +To disable it: + +```ruby +Feature.disable(:board_multi_select) +``` |