diff --git a/doc/user/project/img/labels_default_v12_1.png b/doc/user/project/img/labels_default_v12_1.png
deleted file mode 100644
index b36b5dac80bda563bd440efc892c9086dc0fdd55..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_default_v12_1.png and /dev/null differ
diff --git a/doc/user/project/img/labels_epic_sidebar_v12_1.png b/doc/user/project/img/labels_epic_sidebar_v12_1.png
deleted file mode 100644
index 13fbab33e2639a0ca64da3373544f348d86b0e6f..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_epic_sidebar_v12_1.png and /dev/null differ
diff --git a/doc/user/project/img/labels_generate_default_v12_1.png b/doc/user/project/img/labels_generate_default_v12_1.png
deleted file mode 100644
index cbdda2ab4dd5d95cf5fd3a6117325178fa0f005b..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_generate_default_v12_1.png and /dev/null differ
diff --git a/doc/user/project/img/labels_group_issues_v12_1.png b/doc/user/project/img/labels_group_issues_v12_1.png
deleted file mode 100644
index 3f8f93c1dfd14f7d19c855ccfa83f03df4d71afc..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_group_issues_v12_1.png and /dev/null differ
diff --git a/doc/user/project/img/labels_key_value_v12_1.png b/doc/user/project/img/labels_key_value_v12_1.png
index 52906b7b458b6ae6700ba8154c243f0c229fc652..82a6856bca7bcd642a83f3638a339dbcd5e16d27 100644
Binary files a/doc/user/project/img/labels_key_value_v12_1.png and b/doc/user/project/img/labels_key_value_v12_1.png differ
diff --git a/doc/user/project/img/labels_project_list_search.png b/doc/user/project/img/labels_project_list_search.png
deleted file mode 100644
index 512d7767e6e37a5119d76f01b527c4de344e1604..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_project_list_search.png and /dev/null differ
diff --git a/doc/user/project/img/labels_promotion_v12_1.png b/doc/user/project/img/labels_promotion_v12_1.png
deleted file mode 100644
index 7cd8ff24e02adc67c02410df6610676df2f40bbe..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_promotion_v12_1.png and /dev/null differ
diff --git a/doc/user/project/img/labels_sidebar.png b/doc/user/project/img/labels_sidebar.png
deleted file mode 100644
index 454a0ca3f07ce011e209cc49d61f76db93a0d984..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_sidebar.png and /dev/null differ
diff --git a/doc/user/project/img/labels_sidebar_assign.png b/doc/user/project/img/labels_sidebar_assign.png
deleted file mode 100644
index 5b7fb78b0329469d9f636f432b9017f0bda839b3..0000000000000000000000000000000000000000
Binary files a/doc/user/project/img/labels_sidebar_assign.png and /dev/null differ
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md
index b1334f0b0b04956ca4e1db489808816a2dfec099..cacacec56717c3690e50644a63fd7e55dda29d01 100644
--- a/doc/user/project/issue_board.md
+++ b/doc/user/project/issue_board.md
@@ -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
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index e4264615488403bb88ddbf2d05a6553916c9ae6b..a5a7fc34ef9387fdbea07b3c32e4e886dd6ed2be 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -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)**
-
+## 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}**).
-
+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.
-
+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.
-
+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:
-
+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}**).
-
+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:
-
+- `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.
-
-
-
-## 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 |
-|:----------------------:|:--------------------------:|
-|  |  |
-
-## 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)**
-
+> [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:
+
-- 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::`.
-
+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.
## 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.
-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.
-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.
-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.
diff --git a/doc/user/search/index.md b/doc/user/search/index.md
index 82dd4c4167ae2dd89b1563ee755946ad807dfddd..a7a34103d0b365b7c2c9ebc71ed708ba6f62f22b 100644
--- a/doc/user/search/index.md
+++ b/doc/user/search/index.md
@@ -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