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

Revamp labels documentation

See merge request gitlab-org/gitlab!24095

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

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)**
 
-![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

@@ -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