Skip to content

G
gitlab-ce
Commit 60da157e authored by Russell Dickenson's avatar Russell Dickenson
Browse files
Options

Merge branch 'docs-labels-cleanup' into 'master' 

Revamp labels documentation

See merge request gitlab-org/gitlab!24095
parents 553522d5 e355afb4
Show whitespace changes
Inline Side-by-side
Showing with 166 additions and 189 deletions
doc/user/project/issue_board.md
View file @ 60da157e
......@@ -423,7 +423,7 @@ something between lists by changing a label.
A typical workflow of using the Issue Board would be:
1. You have [created](labels.md#creating-labels) and [prioritized](labels.md#label-priority)
1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority)
labels so that you can easily categorize your issues.
1. You have a bunch of issues (ideally labeled).
1. You visit the Issue Board and start [creating lists](#creating-a-new-list) to
......
doc/user/project/labels.md
View file @ 60da157e
......@@ -3,264 +3,234 @@
## Overview
Labels allow you to categorize epics, issues, and merge requests using descriptive titles like
`bug`, `feature request`, or `docs`. Each label also has a customizable color. They
allow you to quickly and dynamically filter and manage epics, issues and merge requests you
care about, and are visible throughout GitLab in most places where issues and merge
requests are located.
`bug`, `feature request`, or `docs`, as well as customizable colors. They allow you to quickly
and dynamically filter and manage epics, issues, and merge requests, and are a key
part of [issue boards](issue_board.md).
You can use labels to help [search](../search/index.md#issues-and-merge-requests) in
lists of issues, merge requests, and epics, as well as [search in issue boards](../search/index.md#issue-boards).
## Project labels and group labels
In GitLab, you can create project and group labels:
There are two types of labels in GitLab:
- **Project labels** can be assigned to issues and merge requests in that project only.
- **Group labels** can be assigned to any epics, issue and merge request in any project in
that group, or any subgroups of the group.
## Scoped labels **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
Scoped labels allow teams to use the simple and familiar label feature to
annotate their epics, issues, merge requests, and epics to achieve custom fields and
custom workflow states by leveraging a special label title syntax.
A scoped label is a kind of label defined by a special double-colon syntax
in the label’s title, using the format `key::value`. For example:
- **Group labels** can be assigned to issues and merge requests in any project in
the selected group or its subgroups.
- They can also be assigned to epics in the selected group or its subgroups.**(ULTIMATE)**
![A sample scoped label](img/labels_key_value_v12_1.png)
## Assign and unassign labels
An issue, epic, or merge request cannot have two scoped labels with the same key.
For example, if an issue is already labeled `priority::3`, and then you apply the
`priority::2` label to it, `priority::3` is automatically removed.
Every issue, merge request and epic can be assigned any number of labels. The labels are
managed in the right sidebar, where you can assign or unassign labels as needed.
This functionality is demonstrated in a video titled [Use scoped labels in GitLab 11.10 for custom fields and custom workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
### Labels with multiple colon pairs
If labels have multiple instances of `::`, the longest path from left to right, until
the last `::`, is considered the "key" or the "scope".
For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on
the same issue. Adding the latter label will automatically remove the former due to
the shared scope of `nested::key1`.
`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue,
as these are considered to use two different label scopes, `nested::key1` and `nested::key2`.
### Workflows with scoped labels
Suppose you wanted a custom field in issues to track the platform operating system
that your features target, where each issue should only target one platform. You
would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`,
etc., as necessary. Applying any one of these labels on a given issue would
automatically remove any other existing label that starts with `platform::`.
The same pattern could be applied to represent the workflow states of your teams.
Suppose you have the labels `workflow::development`, `workflow::review`, and
`workflow::deployed`. If an issue already has the label `workflow::development`
applied, and a developer wanted to advance the issue to `workflow::review`, they
would simply apply that label, and the `workflow::development` label would
automatically be removed. This behavior already exists when you move issues
across label lists in an [issue board](issue_board.md#creating-workflows), but
now, team members who may not be working in an issue board directly would still
be able to advance workflow states consistently in issues themselves.
To assign a label to an issue, merge request or epic:
## Creating labels
1. In the label section of the sidebar, click **Edit**, then:
- In the list, click the labels you want. Each label is flagged with a checkmark.
- Find labels by entering a search query and clicking search (**{search}**), then
click on them. You can search repeatedly and add more labels.
1. Click **X** or anywhere outside the label section and the labels are applied.
NOTE: **Note:**
A permission level of Reporter or higher is required to create labels.
You can also assign a label with the [`/assign @username` quick action](quick_actions.md).
### New project label
## Label management
To create a **project label**, navigate to **Issues > Labels** in the project.
This page only shows the project labels in this project, and the group labels of the
project's parent group.
Users with a [permission level](../permissions.md) of Reporter or higher are able to create
and edit labels.
Click the **New label** button. Enter the title, an optional description, and the
background color. Click **Create label** to create the label.
### Project labels
If a project has no labels, you can generate a default set of project labels from
its empty label list page:
View the project labels list by going to the project and clicking **Issues > Labels**.
The list includes all labels that are defined at the project level, as well as all
labels inherited from the parent group. You can filter the list by entering a search
query at the top and clicking search (**{search}**).
![Labels generate default](img/labels_generate_default_v12_1.png)
To create a new project label:
GitLab will add the following default labels to the project:
1. Navigate to **Issues > Labels** in the project.
1. Click the **New label** button.
- Enter the title.
- (Optional) Enter a description.
- (Optional) Select a background color by clicking on the available colors, or input
a hex color value for a specific color.
1. Click **Create label** to create the label.
![Labels default](img/labels_default_v12_1.png)
You can also create a new project label from within an issue or merge request. In the
label section of the right sidebar of an issue or a merge request:
### New group label
1. Click **Edit**.
1. Click **Create project label**.
- Fill in the name field. Note that you can't specify a description if creating a label
this way. You can add a description later by editing the label (see below).
- (Optional) Select a color by clicking on the available colors, or input a hex
color value for a specific color.
1. Click **Create**.
To create a **group label**, navigate to **Issues > Labels** in the **group** and create
it from there. This page only shows group labels in this group.
Once created, you can edit a label by clicking the pencil (**{pencil}**), or delete
a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button
and selecting **Delete**.
Alternatively, you can create group labels from the Epic sidebar. **(ULTIMATE)**
#### Promote a project label to a group label
Please note that the created label will belong to the immediate group to which the
epic belongs.
If you previously created a project label and now want to make it available for other
projects within the same group, you can promote it to a group label. If other projects
in the same group have a label with the same name, they will all be overwritten by
the new group label.
![Create Labels from Epic](img/labels_epic_sidebar_v12_1.png)
WARNING: **Caution:**
Promoting a label is a permanent action, and cannot be reversed.
Group labels appear in every label list page of the group's child projects.
To promote a project label to a group label:
![Labels list](img/labels_list_v12_1.png)
1. Navigate to **Issues > Labels** in the project.
1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and
select **Promote to group label**.
### New project label from sidebar
### Group labels
From the sidebar of an issue or a merge request, you can create a new **project label**
inline immediately, instead of navigating to the project label list page.
View the group labels list by going to the group and clicking **Issues > Labels**.
The list includes all labels that are defined at the group level only. It does not
list any labels that are defined in projects. You can filter the list by entering
a search query at the top and clicking search (**{search}**).
![Labels inline](img/labels_new_label_from_sidebar.gif)
To create a **group label**, navigate to **Issues > Labels** in the group and
follow the same process as [creating a project label](#project-labels).
## Editing labels
#### Create group labels from epics **(ULTIMATE)**
NOTE: **Note:**
A permission level of Reporter or higher is required to edit labels.
You can create group labels from the Epic sidebar. The labels you create will
belong to the immediate group to which the epic belongs. The process is the same as
creating a [project label from an issue or merge request](#project-labels).
To update a label, navigate to **Issues > Labels** in the project or group
and click the pencil icon. The title, description and color can be changed.
### Generate default labels
To delete a label, click the three dots next to the `Subscribe` button, and select
**Delete**.
If a project or group has no labels, you can generate a default set of project or group
labels from the label list page. The page will show a **Generate a default set of labels**
button if the list is empty, and clicking it will add the following default labels
to the project:
![Delete label](img/labels_delete_v12_1.png)
- `bug`
- `confirmed`
- `critical`
- `discussion`
- `documentation`
- `enhancement`
- `suggestion`
- `support`
### Promoting project labels to group labels
If you are expanding from a few projects to a larger number of projects within the
same group, you may want to share the same label among multiple projects in the same
group. If you previously created a project label and now want to make it available
for other projects, you can promote it to a group label.
From the project label list page, you can promote a project label to a group label.
This will merge all project labels with the same name into a single group label, across
all projects in this group. All issues and merge requests that were previously
assigned one of these project labels will now be assigned the new group label. This
action cannot be reversed and the changes are permanent.
![Labels promotion](img/labels_promotion_v12_1.png)
## Assigning labels from the sidebar
Every epic, issue, and merge request can be assigned any number of labels. The labels are
visible on every epic, issue and merge request page, in the sidebar and on your issue boards.
From the sidebar, you can assign or unassign a label to the object (i.e. label or
unlabel it). You can also perform this as a [quick action](quick_actions.md),
in a comment.
| View labels in sidebar | Assign labels from sidebar |
|:----------------------:|:--------------------------:|
| ![Labels sidebar](img/labels_sidebar.png) | ![Labels sidebar assign](img/labels_sidebar_assign.png) |
## Searching for project labels
To search for project labels, go to **Issues > Labels** in the left sidebar, and enter
your search query in the **Filter** field.
## Scoped labels **(PREMIUM)**
![Labels project list search](img/labels_project_list_search.png)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
GitLab will check both the label titles and descriptions for the search.
Scoped labels allow teams to use the label feature to annotate issues, merge requests
and epics with mutually exclusive labels. This can enable more complicated workflows
by preventing certain labels from being used together.
## Filtering by label
A label is scoped when it uses a special double-colon (`::`) syntax in the label’s
title, for example:
The following can be filtered by labels:
![Sample scoped labels](img/labels_key_value_v12_1.png)
- Epic lists **(ULTIMATE)**
- Issue lists
- Merge Request lists
- Issue Boards
An issue, merge request or epic cannot have two scoped labels, of the form `key::value`,
with the same `key`. Adding a new label with the same `key`, but a different `value` will
cause the previous `key` label to be replaced with the new label.
### Filtering in list pages
Example use case:
- From the project issue list page and the project merge request list page, you can
[filter](../search/index.md#issues-and-merge-requests) by:
- Group labels (including subgroup ancestors)
- Project labels
1. An issue is identified as being low priority, and a `priority::low` project
label is added to it.
1. After more review the issue priority is increased, and a `priority::high` label is
added.
1. GitLab automatically removes the `priority::low` label, as an issue should not
have two priority labels at the same time.
- From the group epic lists page, issue list page and the group merge request list page, you can
[filter](../search/index.md#issues-and-merge-requests) by:
- Group labels (including subgroup ancestors and subgroup descendants)
- Project labels
### Workflows with scoped labels
- You can [filter](../search/index.md#issues-and-merge-requests) the group epic list
page by: **(ULTIMATE)**
- Current group labels
- Descendant group labels
Suppose you wanted a custom field in issues to track the operating system platform
that your features target, where each issue should only target one platform. You
would then create three labels `platform::iOS`, `platform::Android`, `platform::Linux`.
Applying any one of these labels on a given issue would automatically remove any other
existing label that starts with `platform::`.
![Labels group issues](img/labels_group_issues_v12_1.png)
The same pattern could be applied to represent the workflow states of your teams.
Suppose you have the labels `workflow::development`, `workflow::review`, and
`workflow::deployed`. If an issue already has the label `workflow::development`
applied, and a developer wanted to advance the issue to `workflow::review`, they
would simply apply that label, and the `workflow::development` label would
automatically be removed. This behavior already exists when you move issues
across label lists in an [issue board](issue_board.md#creating-workflows), but
now, team members who may not be working in an issue board directly would still
be able to advance workflow states consistently in issues themselves.
### Filtering in issue boards
This functionality is demonstrated in a video regarding
[using scoped labels for custom fields and workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
- From [project boards](issue_board.md), you can use the [search and filter bar](../search/index.md#issue-boards)
to filter by:
- Group labels
- Project labels
### Scoped labels with nested scopes
- From [group issue boards](issue_board.md#group-issue-boards-premium), you can use the
[search and filter bar](../search/index.md#issue-boards) to filter by group labels only. **(PREMIUM)**
You can create a label with a nested scope by using multiple double colons `::` when creating
it. In this case, everything before the last `::` will be the scope.
- From [project boards](issue_board.md), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
you can filter by: **(STARTER)**
- Group labels
- Project labels
For example, `workflow::backend::review` and `workflow::backend::development` are valid
scoped labels, but they **can't** exist on the same issue at the same time, as they
both share the same scope, `workflow::backend`.
- From [group issue boards](issue_board.md#group-issue-boards-premium), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
you can filter by group labels only. **(STARTER)**
Addtionally, `workflow::backend::review` and `workflow::frontend::review` are valid
scoped labels, and they **can** exist on the same issue at the same time, as they
both have different scopes, `workflow::frontend` and `workflow::backend`.
## Subscribing to labels
From the project label list page and the group label list page, you can subscribe
to [notifications](../profile/notifications.md) of a given label, to alert you
that the label has been assigned to an epic, issue, or merge request.
From the project label list page and the group label list page, you can click **Subscribe**
to the right of any label to enable [notifications](../profile/notifications.md) for that
label. You will be notified whenever the label is assigned to an epic,
issue, or merge request.
If you are subscribing to a group label from within a project, you can select to subscribe
to label notifications for the project only, or the whole group.
![Labels subscriptions](img/labels_subscriptions_v12_1.png)
## Label priority
>**Notes:**
>
> - Introduced in GitLab 8.9.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/18554) considers changing this.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14189) in GitLab 8.9.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/issues/14523) considers changing this.
Labels can have relative priorities, which are used in the "Label priority" and
"Priority" sort orders of the epic, issue, and merge request list pages.
Labels can have relative priorities, which are used in the **Label priority** and
**Priority** sort orders of the epic, issue, and merge request list pages. Prioritization
for both group and project labels happens at the project level, and cannot be done
from the group label list.
From the project label list page, star a label to indicate that it has a priority.
![Labels prioritized](img/labels_prioritized_v12_1.png)
Drag starred labels up and down the list to change their priority. Higher in the list
means higher priority. Prioritization happens at the project level, only on the project
label list page, and not on the group label list page.
However, both project and group
labels can be prioritized on the project label list page since both types are displayed
on the project label list page.
Drag starred labels up and down the list to change their priority, where higher in the list
means higher priority.
![Drag to change label priority](img/labels_drag_priority_v12_1.gif)
On the epic, merge request and issue pages, for both groups and projects, you can sort by `Label priority`
and `Priority`, which account for objects (epic, issues, and merge requests) that have prioritized
labels assigned to them.
On the epic, merge request, and issue list pages, for both groups and projects, you
can sort by `Label priority` or `Priority`.
If you sort by `Label priority`, GitLab considers this sort comparison order:
If you sort by `Label priority`, GitLab uses this sort comparison order:
- Object with a higher priority prioritized label.
- Object without a prioritized label.
1. Items with a higher priority label.
1. Items without a prioritized label.
Ties are broken arbitrarily. Note that we _only_ consider the highest prioritized label
in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/18554)
considers changing this.
Ties are broken arbitrarily. Note that only the highest prioritized label is checked,
and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/issues/14523)
for more information.
![Labels sort label priority](img/labels_sort_label_priority.png)
If you sort by `Priority`, GitLab considers this sort comparison order:
If you sort by `Priority`, GitLab uses this sort comparison order:
- Due date of the assigned [milestone](milestones/index.md) is sooner, provided
the object has a milestone and the milestone has a due date. If this isn't the case,
consider the object having a due date in the infinite future.
- Object with a higher priority prioritized label.
- Object without a prioritized label.
1. Items with milestones that have due dates, where the soonest assigned [milestone](milestones/index.md)
is listed first.
1. Items with milestones with no due dates.
1. Items with a higher priority label.
1. Items without a prioritized label.
Ties are broken arbitrarily.
......
doc/user/search/index.md
View file @ 60da157e
......@@ -33,8 +33,15 @@ Follow these steps to filter the **Issues** and **Merge Requests** list pages wi
groups:
1. Click in the field **Search or filter results...**.
1. In the dropdown menu that appears, select the attribute you wish to filter by (for example,
author, assignee, milestone, and so on).
1. In the dropdown menu that appears, select the attribute you wish to filter by:
- Author
- Assignee
- [Milestone](../project/milestones/index.md)
- Release
- [Label](../project/labels.md)
- My-reaction
- Confidential
- Search for this text
1. Select or type the operator to use for filtering the attribute. The following operators are
available:
- `=`: Is
......
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