Key-value labels with replacement logic
- An even lighter weight version of label sets as described in #5805, which itself can be considered a lighter weight version of custom fields: &235
A key-value 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 key-value labels. There are just regular labels in that sense. A label is a key-value label when it’s title follows that syntax.
For example, you could create 4 labels to represent priority as:
Using key-value labels
When you apply key-value 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 key-value label to an object that doesn’t have any label with that key yet, then there’s no replacement.
If you apply multiple key-value 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:4 at the same time, then only
priority:4 survives at the end since that is the last label applied.
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 key-value labels with the same key, the same rule applies when you “commit” that change, only the last key-value 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 key-value 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 key-value label is removed and replaced with the group 2 key-value label.
To help users understand this behavior, key-value 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 colon
This change uses the special colon syntax. This means if a team already using the colon for labels but not wanting this mutual exclusion behavior will need to pick another character. The docs will recommend users replace colon with dash in this case. Also, it means that in previous releases (or in lower tiers), issues/mrs/epics may already have multiple key-value 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 key-value label with the same key, to an issue with already applied key-value labels with that key, all those existing key-value labels will be removed per the above logic.
In future iterations, we would update various parts of the UI to make key-value 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 key-value labels.