Skip to content

G
gitlab-ce
Commit 318e8b11 authored by Marcia Ramos's avatar Marcia Ramos Committed by Mike Lewis
Browse files
Options

Docs: improve Issue Boards overview (to deprecate feature page)

parent b0b5346d
Hide whitespace changes
Inline Side-by-side
Showing with 176 additions and 113 deletions
doc/user/project/issue_board.md
View file @ 318e8b11
......@@ -2,13 +2,44 @@
> [Introduced][ce-5554] in [GitLab 8.11](https://about.gitlab.com/2016/08/22/gitlab-8-11-released/#issue-board).
## Overview
The GitLab Issue Board is a software project management tool used to plan,
organize, and visualize a workflow for a feature or product release.
It can be used as a [Kanban] or a [Scrum] board.
![GitLab Issue Board](img/issue_board.png)
It provides perfect pairing between issue tracking and project management,
keeping everything in the same place, so that you don't need to jump
between different platforms to organize your workflow.
## Overview
With GitLab Issue Boards, you organize your issues in lists that correspond to
their assigned labels, visualizing issues designed as cards throughout that lists.
You define your process and GitLab organizes it for you. You add your labels
then create the corresponding list to pull in your existing issues. When
you're ready, you can drag and drop your issue cards from one step to the next.
![GitLab Issue Board - Core](img/issue_boards_core.png)
**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of
Issue Boards** (version introduced in GitLab 8.11 - August 2016).
### Advanced features of Issue Boards
With [GitLab Starter](https://about.gitlab.com/pricing/), you can create
[multiple issue boards](#multiple-issue-boards) for a given project. **[STARTER]**
With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple
issue boards for your groups, and add lists for [assignees](#assignee-lists) and
[milestones](#milestone-lists). **[PREMIUM]**
Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards)
below.
![GitLab Issue Boards - Premium](img/issue_boards_premium.png)
## How it works
The Issue Board builds on GitLab's existing
[issue tracking functionality](issues/index.md#issue-tracker) and
......@@ -28,15 +59,12 @@ and deploy from one single platform. Issue Boards help you to visualize
and manage the entire process _in_ GitLab.
With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), available
only in [GitLab Enterprise Edition](#features-per-tier),
only in [different tiers of GitLab Enterprise Edition](#gitlab-enterprise-features-for-issue-boards),
you go even further, as you can not only keep yourself and your project
organized from a broader perspective with one Issue Board per project,
but also allow your team members to organize their own workflow by creating
multiple Issue Boards within the same project.
For a visual overview, see our [Issue Board feature page](https://about.gitlab.com/features/issueboard/)
on about.gitlab.com or our [video introduction to Issue Boards](https://www.youtube.com/watch?v=UWsJ8tkHAa8).
## Use cases
There are many ways to use GitLab Issue Boards tailored to your own preferred workflow.
......@@ -111,11 +139,6 @@ to improve their workflow with multiple boards.
Create lists for each of your team members and quickly drag-and-drop issues onto each team member.
## Permissions
[Developers and up](../permissions.md) can use all the functionality of the
Issue Board, that is, create or delete lists and drag issues from one list to another.
## Issue Board terminology
- **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards.
......@@ -126,6 +149,139 @@ Issue Board, that is, create or delete lists and drag issues from one list to an
- **Closed** (default): shows all closed issues. Always appears as the rightmost list.
- **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list.
## Permissions
[Developers and up](../permissions.md) can use all the functionality of the
Issue Board, that is, create or delete lists and drag issues from one list to another.
## GitLab Enterprise features for Issue Boards
GitLab Issue Boards are available on GitLab Core and GitLab.com Free, but some
advanced functionalities are only present in higher tiers: GitLab.com Bronze,
Silver, or Gold, or GitLab self-managed Starter, Premium, and Ultimate, as described
on the following sections.
For a collection of [features per tier](#summary-of-features-per-tier), check the summary below.
### Multiple Issue Boards **[STARTER]**
> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee).
Multiple Issue Boards, as the name suggests, allow for more than one Issue Board
for a given project or group. This is great for large projects with more than one team
or in situations where a repository is used to host the code of multiple
products.
Clicking on the current board name in the upper left corner will reveal a
menu from where you can create another Issue Board and rename or delete the
existing one.
NOTE: **Note:**
The Multiple Issue Boards feature is available for
**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**.
![Multiple Issue Boards](img/issue_boards_multiple.png)
### Configurable Issue Boards **[STARTER]**
> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration).
An Issue Board can be associated with a GitLab [Milestone](milestones/index.md#milestones),
[Labels](labels.md), Assignee and Weight
which will automatically filter the Board issues according to these fields.
This allows you to create unique boards according to your team's need.
![Create scoped board](img/issue_board_creation.png)
You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter
through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board.
![Edit board configuration](img/issue_board_edit_button.png)
If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope".
![Viewing board configuration](img/issue_board_view_scope.png)
### Focus mode **[STARTER]**
> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep).
Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
![Board focus mode](img/issue_board_focus_mode.gif)
### Sum of Issue Weights **[STARTER]**
The top of each list indicates the sum of issue weights for the issues that
belong to that list. This is useful when using boards for capacity allocation,
especially in combination with [assignee lists](#assignee-lists).
![Issue Board summed weights](img/issue_board_summed_weights.png)
### Group Issue Boards **[PREMIUM]**
> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards).
Accessible at the group navigation level, a group issue board offers the same features as a project-level board,
but 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.
NOTE: **Note:**
Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and
one group issue board per group was made available in GitLab 10.6 Core.
![Group issue board](img/group_issue_board.png)
### Assignee lists **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium.
Like a regular list that shows all issues that have the list label, you can add
an assignee list that shows all issues assigned to the given user.
You can have a board with both label lists and assignee lists. To add an
assignee list:
1. Click **Add list**.
1. Select the **Assignee list** tab.
1. Search and click on 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](#dragging-issues-between-lists) to and/or 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.png)
### Milestone lists **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium.
As of 11.2, you're also able to create lists of a milestone. As the name states,
these are lists that filter issues by the assigned milestone, giving you more
freedom and visibility on the Issue Board. To do so:
1. Click **Add list**.
1. Select the **Milestone** tab.
1. Search and click on the milestone.
Similar to the assignee lists, you're now able to [drag issues](#dragging-issues-between-lists)
to and/or from a milestone list to manipulate the milestone of the dragged issues.
As on another list types, click on the trash icon to remove it.
![Milestone lists](img/issue_board_milestone_lists.png)
### Summary of features per tier
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 | Configurable Issue Boards | Assignee Lists |
|----------|--------------------------------|------------------------------|---------------------------|----------------|
| Core / Free | 1 | 1 | No | No |
| Starter / Bronze | Multiple | 1 | Yes | No |
| Premium / Silver | Multiple | Multiple | Yes | Yes |
| Ultimate / Gold | Multiple | Multiple | Yes | Yes |
## Actions you can take on an Issue Board
- [Create a new list](#creating-a-new-list).
......@@ -142,7 +298,7 @@ Issue Board, that is, create or delete lists and drag issues from one list to an
If you are not able to perform one or more of the things above, make sure you
have the right [permissions](#permissions).
## First time using the Issue Board
### First time using the Issue Board
The first time you navigate to your Issue Board, you will be presented with
a default list (**Done**) and a welcoming message that gives
......@@ -157,7 +313,7 @@ which means the system has no way of populating them automatically. That's of
course if the predefined labels don't already exist. If any of them does exist,
the list will be created and filled with the issues that have that label.
## Creating a new list
### Creating a new list
Create a new list by clicking on the **Add list** button at the upper
right corner of the Issue Board.
......@@ -172,7 +328,7 @@ To create a list for a label that doesn't yet exist, simply create the label by
choosing **Create new label**. The label will be created on-the-fly and it will
be immediately added to the dropdown. You can now choose it to create a list.
## Deleting a list
### Deleting a list
To delete a list from the Issue Board use the small trash icon that is present
in the list's heading. A confirmation dialog will appear for you to confirm.
......@@ -180,7 +336,7 @@ in the list's heading. A confirmation dialog will appear for you to confirm.
Deleting a list doesn't have any effect in issues and labels, it's just the
list view that is removed. You can always add it back later if you need.
## Adding issues to a list
### Adding issues to a list
You can add issues to a list by clicking the **Add issues** button that is
present in the upper right corner of the Issue Board. This will open up a modal
......@@ -192,7 +348,7 @@ the list by filtering by author, assignee, milestone and label.
![Bulk adding issues to lists](img/issue_boards_add_issues_modal.png)
## Removing an issue from a list
### Removing an issue from a list
Removing an issue from a list can be done by clicking on the issue card and then
clicking the **Remove from board** button in the sidebar. Under the hood, the
......@@ -201,7 +357,7 @@ board itself.
![Remove issue from list](img/issue_boards_remove_issue.png)
## Issue ordering in a list
### Issue ordering in a list
When visiting a board, issues appear ordered in any list. You are able to change
that order simply by dragging and dropping the issues. The changed order will be saved
......@@ -224,7 +380,7 @@ a given board inside your GitLab instance, any time those two issues are subsequ
loaded in any board in the same instance (could be a different project board or a different group board, for example),
that ordering will be maintained.
## Filtering issues
### Filtering issues
You should be able to use the filters on top of your Issue Board to show only
the results you want. This is similar to the filtering used in the issue tracker
......@@ -232,7 +388,7 @@ since the metadata from the issues and labels are re-used in the Issue Board.
You can filter by author, assignee, milestone and label.
## Creating workflows
### Creating workflows
By reordering your lists, you can create workflows. As lists in Issue Boards are
based on labels, it works out of the box with your existing issues. So if you've
......@@ -267,89 +423,7 @@ to another list the label changes and a system not is recorded.
![Issue Board system notes](img/issue_board_system_notes.png)
## Multiple Issue Boards **[STARTER]**
> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee).
Multiple Issue Boards, as the name suggests, allow for more than one Issue Board
for a given project or group. This is great for large projects with more than one team
or in situations where a repository is used to host the code of multiple
products.
Clicking on the current board name in the upper left corner will reveal a
menu from where you can create another Issue Board and rename or delete the
existing one.
NOTE: **Note:**
The Multiple Issue Boards feature is available for
**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**.
![Multiple Issue Boards](img/issue_boards_multiple.png)
## Configurable Issue Boards **[STARTER]**
> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration).
An Issue Board can be associated with GitLab [Milestone](milestones/index.md#milestones),
[Labels](labels.md), Assignee and Weight
which will automatically filter the Board issues according to these fields.
This allows you to create unique boards according to your team's need.
![Create scoped board](img/issue_board_creation.png)
You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter
through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board.
![Edit board configuration](img/issue_board_edit_button.png)
If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope".
![Viewing board configuration](img/issue_board_view_scope.png)
## Focus mode **[STARTER]**
> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep).
Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
![Board focus mode](img/issue_board_focus_mode.gif)
## Group Issue Boards **[PREMIUM]**
> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards).
Accessible at the group navigation level, a group issue board offers the same features as a project-level board,
but 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.
NOTE: **Note:**
Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and
one group issue board per group was made available in GitLab 10.6 Core.
![Group issue board](img/group_issue_board.png)
## Assignee lists **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium.
Like a regular list that shows all issues that have the list label, you can add
an assignee list that shows all issues assigned to the given user.
You can have a board with both label lists and assignee lists. To add an
assignee list:
1. Click **Add list**.
1. Select the **Assignee list** tab.
1. Search and click on 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](#dragging-issues-between-lists) to and/or 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.png)
## Dragging issues between lists
### Dragging issues between lists
When dragging issues between lists, different behavior occurs depending on the source list and the target list.
......@@ -360,17 +434,6 @@ When dragging issues between lists, different behavior occurs depending on the s
| 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 |
## Features per tier
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 | Configurable Issue Boards | Assignee Lists |
|----------|--------------------------------|------------------------------|---------------------------|----------------|
| Core | 1 | 1 | No | No |
| Starter | Multiple | 1 | Yes | No |
| Premium | Multiple | Multiple | Yes | Yes |
| Ultimate | Multiple | Multiple | Yes | Yes |
## Tips
A few things to remember:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7