Update docs labels CE

doc/user/project/labels.md

@@ -1,174 +1,125 @@
 # Labels
 
-Labels provide an easy way to categorize the issues or merge requests based on
-descriptive titles like `bug`, `documentation` or any other text you feel like.
-They can have different colors, a description, and are visible throughout
-the issue tracker or inside each issue individually.
+## Overview
 
-With labels, you can navigate the issue tracker and filter any bloated
-information to visualize only the issues you are interested in. Let's see how
-that works.
+Labels allow you to categorize issues or 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 issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located.
 
-## Create new labels
+## Project labels and group labels
+
+In GitLab, you can create project and group labels:
+
+- **Project labels** can be assigned to issues or merge requests in that project only. 
+- **Group labels** can be assigned to any issue or merge request of any project in that group. 
+- In the [future](https://gitlab.com/gitlab-org/gitlab-ce/issues/40915), you will be able to assign group labels to issues and merge reqeusts of projects in [subgroups](../group/subgroups/index.md).
+
+## Creating labels
 
 >**Note:**
-A permission level of `Developer` or higher is required in order to manage
-labels.
+A permission level of `Developer` or higher is required in order to create labels.
 
-Head over a single project and navigate to **Issues > Labels**.
+### New project label
 
-The first time you visit this page, you'll notice that there are no labels
-created yet.
+To create a **project label**, navigate to **Issues > Labels** in the project.
 
-Creating a new label from scratch is as easy as pressing the **New label**
-button. From there on you can choose the name, give it an optional description,
-a color and you are set.
+Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label.
 
-When you are ready press the **Create label** button to create the new label.
+If a project has no labels, you can generate a default set of project labels from its empty label list page:
 
-![New label](img/labels_new_label.png)
+![Labels generate default](img/labels_generate_default.png)
 
----
+GitLab will add the following default labels to the  project:
 
-## Default labels
+![Labels default](img/labels_default.png)
 
-The very first time you visit the labels area, it's gonna be empty. In that
-case, it's possible to populate the labels for your project from a set of
-predefined labels.
+### New group label
 
-Click the link to 'Generate a default set of labels' and GitLab will
-generate them for you. There are 8 default generated labels in total:
+To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there.
 
-- bug
-- confirmed
-- critical
-- discussion
-- documentation
-- enhancement
-- suggestion
-- support
+Group labels appear in every label list page of the group's child projects.
 
-## Labels Overview
+![Labels list](img/labels_list.png)
 
-![Default generated labels](img/labels_default.png)
+### New project label from sidebar
 
-You can see that from the labels page you can have an overview of the number of
-issues and merge requests assigned to each label.
+From the sidebar of an issue or a merge request, you can create a create a new **project label** inline immediately, instead of navigating to the project label list page.
 
-## Prioritize labels
+![Labels inline](img/new_label_from_sidebar.gif)
+
+## Editing labels
+
+NOTE: **Note:**
+A permission level of `Developer` or higher is required in order to edit labels.
+
+You can update a label by navigating to **Issues > Labels** in the project ot group and clicking the pencil icon.
+
+You can delete a label by clicking the trash icon.
+
+### 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 across all projects in this group with the same name into a single group label. All issues and merge requests that previously were 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.png)
+
+## Assigning labels from the sidebar
+
+Every issue and merge request can be assigned any number of labels. The labels are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. 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) |
+
+## Filtering issues and merge requests by label
+
+### Filtering in list pages
+
+From the project issue list page and the project merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels and project labels.
+
+From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels and project labels.
+
+![Labels group issues](img/labels_group_issues.png)
+
+### Filtering in issue boards
+
+- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards).
+
+## Subscribing to labels
+
+From the project label list page and the group label list page, you can subscribe to [notifications](../../workflow/notifications.md) of a given label, to alert you that that label has been assigned to an issue or merge request.
+
+![Labels subscriptions](img/labels_subscriptions.png)
+
+## Label priority
 
 >**Notes:**
 >
 > - Introduced in GitLab 8.9.
-> - Priority sorting is based on the highest priority label only. This might
->   change in the future, follow the discussion in
->   https://gitlab.com/gitlab-org/gitlab-ce/issues/18554.
+> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.
 
-Prioritized labels are like any other label, but sorted by priority. This allows
-you to sort issues and merge requests by label priority.
+Labels can have relative priorities, which are used in the "Label priority" and "Priority" sort orders of the issue and merge request list pages.
 
-To prioritize labels, navigate to your project's **Issues > Labels** and click
-on the star icon next to them to put them in the priority list. Click on the
-star icon again to remove them from the list.
+From the project label list page, star a label to indicate that it has a priority. Drag starred labels up and down to change their priority. Higher 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.
 
-From there, you can drag them around to set the desired priority. Priority is
-set from high to low with an ascending order. Labels with no priority, count as
-having their priority set to null.
+![Labels prioritized](img/labels_prioritized.png)
 
-![Prioritize labels](img/labels_prioritize.png)
+On the project and group issue and merge request list pages, you can sort by `Label priority` and `Priority`, which account for objects (issues and merge requests) that have prioritized labels assigned to them.
 
-Now that you have labels prioritized, you can use the 'Label priority' and 'Priority' 
-sort orders in the issues or merge requests tracker.
+If you sort by `Label priority`, GitLab considers this sort comparison order:
 
-In the following, everything applies to both issues and merge requests, but we'll
-refer to just issues for brevity.
+- Object with a higher priority prioritized label.
+- Object without a prioritized label.
 
-The 'Label priority' sort order positions issues with higher priority labels
-toward the top, and issues with lower priority labels toward the bottom. A non-prioritized
-label is considered to have the lowest priority. For a given issue, we _only_ consider the
-highest priority label assigned to it in the comparison. ([We are discussing](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) 
-including all the labels in a given issue for this comparison.) Given two issues
-are equal according to this sort comparison, their relative order is equal, and 
-therefore it's not guaranteed that one will be always above the other.
+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-ce/issues/18554) considers changing this.)
 
-![Label priority sort order](img/label_priority_sort_order.png)
+![Labels sort label priority](img/labels_sort_label_priority.png)
 
-The 'Priority' sort order comparison first considers an issue's milestone's due date,
-(if the issue is assigned a milestone and the milestone's due date exists), and then 
-secondarily considers the label priority comparison above. Sooner due dates results
-a higher sort order. If an issue doesn't have a milestone due date, it is equivalent to
-being assigned to a milestone that has a due date in the infinite future. Given two issues
-are equal according to this two-stage sort comparison, their relative order is equal, and 
-therefore it's not guaranteed that one will be always above the other.
+If you sort by `Priority`, GitLab considers this sort comparison order:
 
-![Priority sort order](img/priority_sort_order.png)
+- Object's assigned [milestone](milestones/index.md)'s due date 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.
 
+Ties are broken arbitrarily.
 
-## Subscribe to labels
-
-If you don’t want to miss issues or merge requests that are important to you,
-simply subscribe to a label. You’ll get notified whenever the label gets added
-to an issue or merge request, making sure you don’t miss a thing.
-
-Go to your project's **Issues > Labels** area, find the label(s) you want to
-subscribe to and click on the eye icon. Click again to unsubscribe.
-
-![Subscribe to labels](img/labels_subscribe.png)
-
-If you work on a large or popular project, try subscribing only to the labels
-that are relevant to you. You’ll notice it’ll be much easier to focus on what’s
-important.
-
-## Create a new label when inside an issue
-
-There are times when you are already inside an issue searching to assign a
-label, only to realize it doesn't exist. Instead of going to the **Labels**
-page and being distracted from your original purpose, you can create new
-labels on the fly.
-
-Expand the issue sidebar and select **Create new label** from the labels dropdown
-list. Provide a name, pick a color and hit **Create**. The new label will be
-ready to used right away!
-
-![New label on the fly](img/labels_new_label_on_the_fly.png)
-
-## Assigning labels to issues and merge requests
-
-There are generally two ways to assign a label to an issue or merge request.
-
-The first one is to assign a label when you first create or edit an issue or
-merge request.
-
-The second way is by using the right sidebar when inside an issue or merge
-request. Expand it and hit **Edit** in the labels area. Start typing the name
-of the label you are looking for to narrow down the list, and select it. You
-can add more than one labels at once. When done, click outside the sidebar area
-for the changes to take effect.
-
-![Assign label in sidebar](img/labels_assign_label_sidebar.png)
-![Save labels in sidebar](img/labels_assign_label_sidebar_saved.png)
-
----
-
-To remove labels, expand the left sidebar and unmark them from the labels list.
-Simple as that.
-
-##  Use labels to filter issues
-
-Once you start adding labels to your issues, you'll see the benefit of it.
-Labels can have several uses, one of them being the quick filtering of issues
-or merge requests.
-
-Pick an existing label from the dropdown _Label_ menu or click on an existing
-label from the issue tracker. In the latter case, you also get to see the
-label description like shown below.
-
-![Filter labels](img/labels_filter.png)
-
----
-
-And if you added a description to your label, you can see it by hovering your
-mouse over the label in the issue tracker or wherever else the label is
-rendered.
-
-![Label tooltips](img/labels_description_tooltip.png)
+![Labels sort priority](img/labels_sort_priority.png)