Skip to content

G
gitlab-ce
Commit c9e98f53 authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski Committed by Suzanne Selhorn
Browse files
Options

CTRT edits to Labels documentation 

Part of TW FY23Q1 OKR
parent 0d9b1b4a
Hide whitespace changes
Inline Side-by-side
Showing with 296 additions and 157 deletions
doc/api/group_labels.md
View file @ c9e98f53
......@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21368) in GitLab 11.8.
This API supports managing [group labels](../user/project/labels.md#project-labels-and-group-labels).
This API supports managing [group labels](../user/project/labels.md#types-of-labels).
It allows users to list, create, update, and delete group labels. Furthermore, users can subscribe to and
unsubscribe from group labels.
......
doc/user/project/issue_board.md
View file @ c9e98f53
......@@ -536,7 +536,7 @@ changing a label.
A typical workflow of using an issue board would be:
1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority)
1. You [create](labels.md#create-a-label) and [prioritize](labels.md#set-label-priority)
labels to categorize your issues.
1. You have a bunch of issues (ideally labeled).
1. You visit the issue board and start [creating lists](#create-a-new-list) to
......
doc/user/project/issues/sorting_issue_lists.md
View file @ c9e98f53
......@@ -49,7 +49,7 @@ Ties are broken arbitrarily. Only the highest prioritized label is checked,
and labels with a lower priority are ignored.
For more information, see [issue 14523](https://gitlab.com/gitlab-org/gitlab/-/issues/14523).
To learn more about priority labels, read the [Labels](../labels.md#label-priority) documentation.
To learn how to change label priority, see [Label priority](../labels.md#set-label-priority).
## Sorting by last updated
......@@ -98,7 +98,9 @@ When you sort by **Priority**, the issue order changes to sort in this order:
1. Issues with a higher priority label.
1. Issues without a prioritized label.
To learn more about priority, read the [Labels](../labels.md#label-priority) documentation.
Ties are broken arbitrarily.
To learn how to change label priority, see [Label priority](../labels.md#set-label-priority).
## Sorting by title
......
doc/user/project/labels.md
View file @ c9e98f53
......@@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Labels **(FREE)**
As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging
As your count of issues, merge requests, and epics grows in GitLab, it gets more challenging
to keep track of those items. Especially as your organization grows from just a few people to
hundreds or thousands. This is where labels come in. They help you organize and tag your work
so you can track and find the work items you're interested in.
hundreds or thousands. With labels, you can organize and tag your work, and track the work items
you're interested in.
Labels are a key part of [issue boards](issue_board.md). With labels you can:
......@@ -19,132 +19,257 @@ Labels are a key part of [issue boards](issue_board.md). With labels you can:
- [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests),
as well as [issue boards](../search/index.md#issue-boards).
## Project labels and group labels
## Types of labels
There are two types of labels in GitLab:
You can use 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 issues and merge requests in any project in
the selected group or its subgroups.
- They can also be assigned to [epics](../group/epics/index.md) in the selected group or its subgroups.
- **Group labels** can be assigned to issues, merge requests, and [epics](../group/epics/index.md)
in any project in the selected group or its subgroups.
## Assign and unassign labels
> Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5.
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.
You can assign labels to any issue, merge request, or epic.
To assign or unassign a label:
1. In the **Labels** section of the sidebar, click **Edit**.
1. In the **Labels** section of the sidebar, select **Edit**.
1. In the **Assign labels** list, search for labels by typing their names.
You can search repeatedly to add more labels.
The selected labels are marked with a checkmark.
1. Click the labels you want to assign or unassign.
1. Select the labels you want to assign or unassign.
1. To apply your changes to labels, select **X** next to **Assign labels** or select any area
outside the label section.
Alternatively, to unassign a label, click the **X** on the label you want to unassign.
Alternatively, to unassign a label, select the **X** on the label you want to unassign.
You can also assign a label with the `/label` [quick action](quick_actions.md),
remove labels with `/unlabel`, and reassign labels (remove all and assign new ones) with `/relabel`.
You can also assign and unassign labels with [quick actions](quick_actions.md):
## Label management
- Assign labels with `/label`.
- Remove labels with `/unlabel`.
- Remove all labels and assign new ones with `/relabel`.
Users with a [permission level](../permissions.md) of Reporter or higher are able to create
and edit labels.
## View available labels
### Project labels
### View project labels
> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5: the label list in a project also shows all inherited labels.
To view a project's available labels, in the project, go to **Project information > Labels**.
Its list of labels includes both the labels defined at the project level, and
all labels defined by its ancestor groups. For each label, you can see the
project or group path from where it was created. You can filter the list by
entering a search query in the **Filter** field, and then clicking its search
icon (**{search}**).
To view the **project's labels**:
To create a new project label:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. In your project, go to **Project information > Labels**.
1. Select the **New label** button.
Or:
1. View an issue or merge request.
1. On the right sidebar, in the **Labels** section, select **Edit**.
1. Select **Manage project labels**.
The list of labels includes both the labels created in the project and
all labels created in the project's ancestor groups. For each label, you can see the
project or group path where it was created.
### View group labels
To view the **group's labels**:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Group information > Labels**.
Or:
1. View an epic.
1. On the right sidebar, in the **Labels** section, select **Edit**.
1. Select **Manage group labels**.
The list includes all labels created only in the group. It does not list any labels created in
the group's projects.
## Create a label
Prerequisites:
- You must have at least the Reporter role for the project or group.
### Create a project label
To create a project label:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Select **New label**.
1. In the **Title** field, enter a short, descriptive name for the label. You
can also use this field to create [scoped, mutually exclusive labels](#scoped-labels).
1. Optional. In the **Description** field, enter additional
information about how and when to use this label.
1. Optional. Select a color by selecting from the available colors, or enter a hex color value for
a specific color in the **Background color** field.
1. Select **Create label**.
### Create a project label from an issue or merge request
You can also create a new project label from an issue or merge request.
Labels you create this way belong to the same project as the issue or merge request.
Prerequisites:
- You must have at least the Reporter role for the project.
To do so:
1. View an issue or merge request.
1. On the right sidebar, in the **Labels** section, select **Edit**.
1. Select **Create project label**.
1. Fill in the name field. You can't specify a description if creating a label this way.
You can add a description later by [editing the label](#edit-a-label).
1. Optional. Select a color by selecting from the available colors, or enter a hex color value for
a specific color.
1. Select **Create**.
### Create a group label
To create a group label:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Group information > Labels**.
1. Select **New label**.
1. In the **Title** field, enter a short, descriptive name for the label. You
can also use this field to create [scoped, mutually exclusive labels](#scoped-labels).
1. Optional. In the **Description** field, you can enter additional
1. Optional. In the **Description** field, enter additional
information about how and when to use this label.
1. Optional. Select a background color for the label by selecting one of the
available colors, or by entering a hex color value in the **Background color**
field.
1. Optional. Select a color by selecting from the available colors, or enter a hex color value for
a specific color in the **Background color** field.
1. Select **Create label**.
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:
### Create a group label from an epic **(PREMIUM)**
You can also create a new group label from an epic.
Labels you create this way belong to the same group as the epic.
Prerequisites:
- You must have at least the Reporter role for the group.
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 do so:
To edit a label after you create it, select (**{pencil}**).
1. View an epic.
1. On the right sidebar, in the **Labels** section, select **Edit**.
1. Select **Create group label**.
1. Fill in the name field. You can't specify a description if creating a label this way.
You can add a description later by [editing the label](#edit-a-label).
1. Optional. Select a color by selecting from the available colors,enter input a hex color value
for a specific color.
1. Select **Create**.
To delete a project label, select (**{ellipsis_v}**) next to the **Subscribe** button
and select **Delete** or select **Delete** when you edit a label.
## Edit a label
Prerequisites:
- You must have at least the Reporter role for the project or group.
### Edit a project label
To edit a **project** label:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Next to the label you want to edit, select **Edit** (**{pencil}**).
### Edit a group label
To edit a **group** label:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Group information > Labels**.
1. Next to the label you want to edit, select **Edit** (**{pencil}**).
## Delete a label
WARNING:
If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion.
If you delete a label, it is permanently deleted. All references to the label are removed from the
system and you cannot undo the deletion.
Prerequisites:
#### Promote a project label to a group label
- You must have at least the Reporter role for the project.
### Delete a project label
To delete a **project** label:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Either:
- Next to the **Subscribe** button, select (**{ellipsis_v}**).
- Next to the label you want to edit, select **Edit** (**{pencil}**).
1. Select **Delete**.
### Delete a group label
To delete a **group** label:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Group information > Labels**.
1. Either:
- Next to the **Subscribe** button, select (**{ellipsis_v}**).
- Next to the label you want to edit, select **Edit** (**{pencil}**).
1. Select **Delete**.
## Promote a project label to a group label
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231472) in GitLab 13.6: promoting a project label keeps that label's ID and changes it into a group label. Previously, promoting a project label created a new group label with a new ID and deleted the old label.
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.
You might want to make a project label available for other
projects in the same group. Then, you can promote the label to a group label.
If other projects in the same group have a label with the same title, they are all
merged with the new group label. If a group label with the same title exists, it is
also merged.
All issues, merge requests, issue board lists, issue board filters, and label subscriptions
with the old labels are assigned to the new group label.
WARNING:
Promoting a label is a permanent action and cannot be reversed.
The new group label has the same ID as the previous project label.
Prerequisites:
WARNING:
Promoting a label is a permanent action, and cannot be reversed.
- You must have at least the Reporter role for the project.
- You must have at least the Reporter role for the project's parent group.
To promote a project label to a group label:
1. Navigate to **Project information > Labels** in the project.
1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and
select **Promote to group label**.
### Group labels
All issues, merge requests, issue board lists, issue board filters, and label subscriptions
with the old labels are assigned to the new group label.
The new group label has the same ID as the previous project label.
To view the group labels list, navigate to the group and click **Group information > 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}**).
## Generate default project labels
To create a **group label**, navigate to **Group information > Labels** in the group and
follow the same process as [creating a project label](#project-labels).
If a project or its parent group has no labels, you can generate a default set of project
labels from the label list page.
#### Create group labels from epics **(ULTIMATE)**
Prerequisites:
You can create group labels from the epic sidebar. The labels you create
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).
- You must have at least the Reporter role for the project.
- The project must have no labels present.
### Generate default labels
To add the default labels to the project:
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 shows a **Generate a default set of labels**
button if the list is empty. Select the button to add the following default labels
to the project:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Select **Generate a default set of labels**.
The following labels are created:
- `bug`
- `confirmed`
......@@ -157,131 +282,143 @@ to the project:
## Scoped labels **(PREMIUM)**
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.
A label is scoped when it uses a special double-colon (`::`) syntax in the label's
title, for example:
Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive
labels. By preventing certain labels from being used together, you can create more complex workflows.
![Scoped labels](img/labels_key_value_v13_5.png)
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`
causes the previous `key` label to be replaced with the new label.
A scoped label uses a double-colon (`::`) syntax in its title, for example: `workflow::in-review`.
For example:
An issue, merge request, or epic cannot have two scoped labels, of the form `key::value`,
with the same `key`. If you add a new label with the same `key` but a different `value`,
the previous `key` label is replaced with the new label.
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.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a video overview, see [Scoped Labels Speed Run](https://www.youtube.com/watch?v=ebyCiKMFODg).
### Filter by scoped labels
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12285) in GitLab 14.4.
To filter issue, merge request, or epic lists for ones with labels that belong to a given scope, enter
To filter issue, merge request, or epic lists by a given scope, enter
`<scope>::*` in the searched label name.
For example, filtering by the `platform::*` label returns issues that have `platform::iOS`,
`platform::Android`, or `platform::Linux` labels.
NOTE:
This is not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests).
Filtering by scoped labels not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests).
### Scoped labels examples
**Example 1.** Updating issue priority:
1. You decide that an issue is of low priority, and assign it the `priority::low` label.
1. After more review, you realize the issue's priority is higher increased, and you assign it the
`priority::high` label.
1. Because an issue shouldn't have two priority labels at the same time, GitLab removes the
`priority::low` label.
**Example 2.** You want a custom field in issues to track the operating system platform
that your features target, where each issue should only target one platform.
You create three labels:
- `platform::iOS`
- `platform::Android`
- `platform::Linux`
If you assign any of these labels to an issue automatically removes any other existing label that
starts with `platform::`.
**Example 3.** You can use scoped labels to represent the workflow states of your teams.
### Workflows with scoped labels
Suppose you have the following 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::`.
- `workflow::development`
- `workflow::review`
- `workflow::deployed`
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#create-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.
If an issue already has the label `workflow::development` and a developer wants to show that the
issue is now under review, they assign the `workflow::review`, and the `workflow::development` label
is removed.
This functionality is demonstrated in a video regarding
[using scoped labels for custom fields and workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
The same happens when you move issues across label lists in an
[issue board](issue_board.md#create-workflows). With scoped labels, team members not working in an
issue board can also advance workflow states consistently in issues themselves.
### Scoped labels with nested scopes
For a video explanation, see:
<div class="video-fallback">
See the video: <a href="https://www.youtube.com/watch?v=4BCBby6du3c">Use scoped labels for custom fields and custom workflows</a>.
</div>
<figure class="video-container">
<iframe src="https://www.youtube.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
### Nested scopes
You can create a label with a nested scope by using multiple double colons `::` when creating
it. In this case, everything before the last `::` is the scope.
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`.
For example, if your project has these labels:
Additionally, `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`.
- `workflow::backend::review`
- `workflow::backend::development`
- `workflow::frontend::review`
## Subscribing to labels
An issue **can't** have both `workflow::backend::review` and `workflow::backend::development`
labels at the same time, because they both share the same scope: `workflow::backend`.
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 are notified whenever the label is assigned to an epic,
issue, or merge request.
On the other hand, an issue **can** have both `workflow::backend::review` and `workflow::frontend::review`
labels at the same time, because they both have different scopes: `workflow::frontend` and `workflow::backend`.
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.
## Receive notifications when a label is used
![Labels subscriptions](img/labels_subscriptions_v13_5.png)
You can subscribe to a label to [receive notifications](../profile/notifications.md) whenever the
label is assigned to an issue, merge request, or epic.
## Label priority
To subscribe to a label:
Labels can have relative priorities, which are used in the **Label priority** and
**Priority** sort orders of issues 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.
1. [View the label list page.](#view-available-labels)
1. To the right of any label, select **Subscribe**.
1. Optional. If you are subscribing to a group label from a project, select either:
- **Subscribe at project level** to be notified about events in this project.
- **Subscribe at group level**: to be notified about events in the whole group.
NOTE:
Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this.
## Set label priority
From the project label list page, star a label to indicate that it has a priority.
![Labels prioritized](img/labels_prioritized_v13_5.png)
Labels can have relative priorities, which are used when you sort issue and merge request lists
by [label priority](issues/sorting_issue_lists.md#sorting-by-label-priority) and [priority](issues/sorting_issue_lists.md#sorting-by-priority).
Drag starred labels up and down the list to change their priority, where higher in the list
means higher priority.
When prioritizing labels, you must do it from a project.
It's not possible to do it from the group label list.
![Drag to change label priority](img/labels_drag_priority_v12_1.gif)
NOTE:
Priority sorting is based on the highest priority label only.
[This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this.
On the merge request and issue list pages (for both groups and projects) you
can sort by `Label priority` or `Priority`.
Prerequisites:
If you sort by `Label priority`, GitLab uses this sort comparison order:
- You must have at least the Reporter role for the project.
1. Items with a higher priority label.
1. Items without a prioritized label.
To prioritize a label:
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.
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Project information > Labels**.
1. Next to a label you want to prioritize, select the star (**{star-o}**).
![Labels sort label priority](img/labels_sort_label_priority.png)
![Labels prioritized](img/labels_prioritized_v13_5.png)
If you sort by `Priority`, GitLab uses this sort comparison order:
This label now appears at the top of the label list, under **Prioritized Labels**.
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.
To change the relative priority of these labels, drag them up and down the list.
The labels higher in the list get higher priority.
Ties are broken arbitrarily.
![Drag to change label priority](img/labels_drag_priority_v12_1.gif)
![Labels sort priority](img/labels_sort_priority.png)
To learn what happens when you sort by priority or label priority, see
[Sorting and ordering issue lists](issues/sorting_issue_lists.md).
## Troubleshooting
......
doc/user/search/index.md
View file @ c9e98f53
......@@ -194,7 +194,7 @@ Some filters can be added multiple times. These include but are not limited to a
You can search your [To-Do List](../todos.md) by "to do" and "done".
You can filter to-do items per project, author, type, and action.
Also, you can sort them by [**Label priority**](../../user/project/labels.md#label-priority),
Also, you can sort them by [**Label priority**](../../user/project/labels.md#set-label-priority),
**Last created**, and **Oldest created**.
## Projects
......
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