Scoped labels with replacement logic
internal customer since at least Plan team and other product development teams and other GitLab departments (including marketing) are using issue boards for workflow, and we can use this with workflow. Also, priority and severity labels will use this.
[ Frontend issue: https://gitlab.com/gitlab-org/gitlab-ee/issues/10277 ]
Background
- An even lighter weight version of label sets as described in https://gitlab.com/gitlab-org/gitlab-ee/issues/5805, which itself can be considered a lighter weight version of custom fields: &235
Main concept
A scoped label is a specific kind of label defined only by a special colon syntax in the label’s title, namely key::value
. There is no different way to create and otherwise manage scoped labels. There are just regular labels in that sense. A label is a scoped label when its title follows that syntax.
For example, you could create 4 labels to represent priority as:
priority::1
priority::2
priority::3
priority::4
Using scoped labels
When you apply scoped labels to issues/mrs/epics, they follow replacement logic. For example, if an issue has priority::3
already and you apply priority::2
to it, priority::3
automatically gets removed from the issue.
If you are applying a scoped label to an object that doesn’t have any label with that key yet, then there’s no replacement.
If you apply multiple scoped labels with the same key all at once, GitLab will do the equivalent of just applying the replacement logic one by one. For example, if an issue already has priority::3
, and you apply the labels priority::1
and priority::4
at the same time, then only priority::4
survives at the end since that is the last label applied.
In the case where labels have multiple sets of ::
, use the longest path for mutual exclusivity check. For example, we would check for exclusivity on some::key::
level instead of some::
- this allows finer grained organization.
These rules are the same in all cases you apply labels, including with the dropdown in the sidebar, when you use quick actions, when you drag an issue to a board label list, when you bulk edit issues/mrs, and via the API. In particular, in this particular issue, we are not changing any UI or otherwise display logic. (Some styling exception below.) More intuitive tweaks to display logic are future iterations.
When you apply labels via the sidebar dropdown, you check and uncheck multiple labels in a dropdown list. Since we are not changing that UI in this issue, if you check multiple scoped labels with the same key, the same rule applies when you “commit” that change, only the last scoped label with that same key survives.
No changes to system notes. System notes still reflect labels being added and removed. Same for notifications.
Constraint is based on title only
Since the constraint is based on title only, the same key space is shared for the entire GitLab instance. That means if you have priority::
labels in different groups and projects, and a given issue can have labels from multiple of those places applied to it, then only one of those priority:
can be on the issue per the above logic. This is a limitation of this design but it is also a benefit because it simplifies the experience. In particular the same logic of last scoped label wins. So if an issue has priority::4
from group 1 already applied, and now you apply priority::4
from group 2, then the group 1 scoped label is removed and replaced with the group 2 scoped label.
Special styling
To help users understand this behavior, scoped labels will be rendered with a question mark icon, such as priority::4 ?
. When users hover on the question mark, there will be a tooltip explainer and/or a docs link.
Already using double colon
This change uses the special colon syntax. This means if a team already using the double colon for labels but not wanting this mutual exclusion behavior will need to pick another character. The docs will recommend users replace the colons with dash in this case. Also, it means that in previous releases (or in lower tiers), issues/mrs/epics may already have multiple scoped labels with the same key assigned. In this case, when the GitLab instance is upgraded to this version and tier, the data is not changed. However, the moment that a user applies a new scoped label with the same key, to an issue with already applied scoped labels with that key, all those existing scoped labels will be removed from that issue per the above logic.
Future iterations
In future iterations, we would update various parts of the UI to make scoped label mutual exclusion more obvious. For example, the sidebar dropdown list would be updated. System notes and notifications would tell you that you are doing replacement instead of addition when dealing with scoped labels.
Designs
New label page
Title fields does not include ::
|
Title field includes ::
|
---|---|
Help text should say "Use :: to create a scoped label set (e.g. priority::1 )" |
Help text should say "Using :: denotes a scoped label set" |
Labels
- Icon- question
-
?
icon should inherit text color of label and link to scoped label sets docs -
4px
space between label text and icon - We've currently got a mix of hover states and no hover states on labels. The
?
should have no hover state for now - The font-size of the icon is currently set to
inherit
so hopefully we shouldn't need to add any CSS for that - Tooltip for scoped labels should have a
Scoped label
header- header should be bold, color is
#A6A6DE
/$indigo-300
- header should be bold, color is
Label | System note |
---|---|
Sidebar | Tooltip |
---|---|
Note: tooltip title should be Scoped label
|
Scoped issues in the search bar
The question mark icon doesn't show up in the search bars:
I think this is fine, and we shouldn't add it for the following reasons:
- Eventually the icon will be removed and a link to the docs will be added to the label popover
- The way the label appears in the search bar is not the way the labels appear elsewhere in the UI; they're using the GFM syntax. It makes sense and is consistent to only show the question mark icon on the styled labels (rounded corners, no tilde)
Documentation
Requirements for documentation. Specific guidelines, but not an exhaustive list of changes needed to enable users for this feature.
-
Location(s)
- Decide whether to include all info as tier-labeled additions to main issues page, or only brief mentions on that page with the bulk of detail on a new page.
- UX/dev/TW should stay in sync on the destination of the
?
link that will appear next to all these labels, and potentially a link in the system note.
-
Content
- Example uses for scoped labels.
- Section about renaming 'legacy scoped labels using ::' (if one wants to ensure preservation of current assignments and the ability to assign multiple to an issue). Mention ability to search labels list for :: to view them all. Bonus: Script to use API to find all issues with multiple :: assignments.
This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.