Optimizing issue Labels in GitLab

@team I am specifically talking about our labels here. These have been a hang up for me when it comes to issue grooming and I think are important in optimizing how we use gitlab

The labels (imo) appear to be a mess and I’m proposing to reorganize them (a task I’ll definitely assign to myself as related to issue grooming stuff). Can people confirm if any of the redundancies are intentional and how we can optimize this system which is quite important to issue grooming and organization of our tasks.

We don’t have scoped labels (unless we pay for the bonus feature which I agree with @salt that we shouldn’t) but there are definitely workarounds and other ways of categorizing labels in hierarchies (note that there are ‘prioritized labels’ as well. I don’t have as much experience as others who have worked on projects that have many subgroups, so any insight here is great.

This was a little tedious as I had to do this by hand but these are our labels currently (may have made mistakes but I was pretty thorough and double checked - still confusing though with number of labels and how they appear).

Here is a list of our current labels (for the listed subgroups, there’s still more smh)
Note the redundancies! Every project (or subgroup) has it’s own “project labels” and also has access to the labels of the ‘group labels’

  • Snowdrift.coop Group Labels:
    • Blocked
    • do next
    • doing
    • easy
    • top priority
    • high priority
    • medium priority
    • low priority
    • needs grooming
    • newcomer
    • quick

Project labels

  • Wiki
    • terminology
  • Snowdrift
    • haskell
    • auth
    • blog article
    • bug
    • crowdmatch
    • dev tooling
    • discussion
    • documentation
    • gathering specs
    • needs clarification
    • new feature/design
    • newcomer-friendly
    • notifications
    • operations
    • patches welcome
    • question
    • sass
    • tests
    • ui/ux
  • Governance
    • board
    • bylaws
    • main
  • Design
    • gather specs
    • ready
    • ux
    • docs
    • bug
    • blog
    • forum
  • Legal
    • money-handling
    • privacy policy
    • terms
  • Outreach
    • Board
    • CiviCRM
    • Discourse
    • Doing
    • blocked
    • blog
    • conference(s)
    • gathering specs
    • grants
    • meetups
    • press
    • project(s)
    • volunteers

Random note: searching for an issue with the title ‘label’ isn’t possible
Helpful note @wolftune: if you want to filter out a certain label you don’t want to see, type “label” and then “!=”

It seems like we need to get rid of redundancies OR if intentional rename those redundancies in a way that makes it clear to which group it belongs to.

1 Appreciation

I updated the Design project labels with namespacing to make it clearer they are from the Design repo. Two labels were promoted to group level, “docs” and “bug”. They seem generic enough to be useful in most repos.

  • Design
    • design–specs
    • design–ready
    • design > ux
    • design > blog
    • design > forum

“–” indicates state, e.g. “design–ready” marks the issue as ready for making initial mockups. It’s a project label because “ready” means something specific within the repo as supplied in the label description (vs. “ready to start writing driver statements”.)

“>” denotes an aspect, or a keyword for the location where the design is being applied. So far these are in common with ops and code repos (a few potentially with outreach), and it would be nice to have them promoted with the colours intact. I kept them namespaced for the moment, maybe only a few people might use them at group level.

1 Appreciation

Thanks for input/update @iko!

That’s definitely in the direction I was thinking of, but there are other options so I was hoping we could come to a consensus about a coherent labeling system that will be consistent across all repos. A main reason I don’t actually think that solution id ideal (it was one of my first thoughts too btw) is because it seems that if you do a search for label = design then none of those labels will come up: that means you cant do a search that yields ALL design labels.

  • If someone wanted to filter out all design-labelled issues, they would have to search:
    “label != [design-specs] [design-ready] [design > ux] [design > blog]” (Which could be really tedious if you didn’t want to look at the snowdrift subgroup which has the most labels)

  • someone who only wanted to look at the design-labelled issues and the governance issues would have to go to both project pages separately, or do a long search that looks like "label = [design-specs] [design-ready] … etc. for both projects

Here’s a proposed alternative:

  • we merge ALL redundancies across separate subgroup/projects into group labels.
    • (in particular all the generic labels like “blocked”, “bug”, “newcomer”)
  • we make a project specific label that is the name of the project
    • i.e. instead of [design > blog] there would be [design] & [blog]

I think that more sophisticated filtering will be really helpful if we get a system that applies well to all repos.


  • This would allow for better searches. For example:

    • if you wanted to search for all design related labels & all governance related labels issues: “label = [governance] [design]”
    • if you wanted to see everything that is not outreach labelled issues: “label != outreach”
  • Consolidating subgroup labels into group labels has two benefits, imo. One is that we reduce the total number of labels which seems like it could reduce time usage and errors in selecting the correct label, (and it’s easier to look at should we want to review them all again in the future) The other benefit is that if want want to use milestones & MR more specifically, the more labels that are in the “group labels” the more they can be applied to those things.

From gitlab docs:

  • 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.

Sorry to tag @team again but I think it’s important for EVERYONE using labels to evaluate their usage and how we may implement them better and review this discussion. I really want to get everyone’s input and consensus on a solution to integrate. This will affect ALL labelled issues. And if anyone is concerned about retroactively fixing issues I can sincerely say this is a task that brings me joy and I am happy to do this for every issue in every repo once we agree on something!

I’m sure there are things I’m not aware of so again, all input and feedback is appreciated! This is definitely something I will be following up with everyone on to make sure there is unanimous consent before any changes are made (from me at least - if there’s motivation for ya’ll to work on repos that you are responsible this might be a trial and error process of optimizing regardless)

At the very least I aim to reduce pointless redundancies!

1 Appreciation

P.S. I’m not sure where ^ proposed labels for each category would go, if they were in group labels they could apply to milestones, MR, etc. so that would be my default assumption

My input:

It depends on what data people want to track/fetch in their role(s). It would be helpful to ask people how they do things, why they do them in a certain way, what problems they encountered if any, before asking how the labels can be implemented better. Their processes are reflected in part in the labels they chose.

As someone in a specific line of work I haven’t any of the use scenarios described and would simply go the repo issues page. One team (or “domain” at a time), where each team currently has 1-2 repos, no need to filter out everything else. I use labels primarily to identify state and filter by aspect within a team list, as previously mentioned. However, if they are frequent use scenarios for others, it could make sense to prioritise them in the setup.

Merging duplicates would be great. (Including potentially confusing ghost tags like “Doing” which keeps getting suggested in the label assignment menu, no longer appearing in the manage labels page but also can’t be re-created because it already exists.)

A project label with the name of the project can help with filtering. One thing, though: consolidating project labels into group labels does not necessarily convey the same meaning in a combination of labels.

The example “[design][blog]” works because “blog” serves as a keyword, and the two exist independently. “[design][ready]” is not the same, because “ready” is linked to a process. People outside of the domain might not know or recall that process. As a project label the tooltip provides a reminder of that means within the project, which is different from “[snowdrift][ready]”. It might be possible to get around it by coming up with more specific terminology than “ready” and “doing” (which shows someone is doing something, but not what stage of the process).

In short, I’m not sure an one-size-fits-all system will apply well across all repos. Teams may have different ways of visualising and organising tasks, and might still want to make use of project labels sometimes.

Anyhow, thanks for looking into it, and good luck finding the best setup.

2 Appreciations

Two observations:

  • I think this needs a lot of time to figure out
  • @alignwaivers it seems you want to figure this out before writing the issue grooming guide/proposal.

Maybe the issue grooming guide could be split up into a part that is not blocked and one that is blocked by figuring out the labels? That way the not-blocked-part could be written and implemented much earlier.

I propose this because I think clarifying issues’ priorities has a high priority, while assigning the right labels has a low priority.

3 Appreciations

I agree with Iko on one point in particular. Labels reflect the working procedures of individual teams, and I don’t think it’s valuable to take their autonomy away from them. The different repos correspond to different people, agendas, priorities. If you put all of the repos in a pot, of course it’s going to look like a mess. That doesn’t mean it’s broken. :slight_smile:

4 Appreciations

Thanks again for input.

I should have clarifyied better - while I’m hoping for a coherent system that is consistent, I completely agree with you @iko and @chreekat it depends on people/roles and their needs, and that might be reflected differently across repos (though I would certainly think it best that all members who use the specific repo are in agreement about usage). My apologies if that came off strong: My thought process was that if it were possible to reconcile them it and make things more consistent it would be easier for newcomers to come in and make assessments, rather than having to ask individually about each repo. A separate guide to each repo may be an option but seems like extra work. But perhaps @photm is correct and this is a low priority, in which case I certainly don’t want to be creating extra work for folks. This is why I was hoping to get feedback from everyone!

I can imagine how this might be true but haven’t thought of a use case. I would assume generally it could be taken as such, but maybe it’s just my strong desire to consolidate the label system more. Again, maybe not as useful as I originally thought

In this instance, ready is a design-only specific label, so in my proposal it would just be a project label called [ready], and [blog] would be a group label as there are other blogs.

@iko would you say you would prefer not to change the labels for the design if it requires adding [design] labels that aren’t helpful to you? It’s seeming like maybe I should table working on this beyond obvious redundancies, and fight my instinct to consolidate as much as possible as it will require a lot of facilitation across the groups and not actually yield much improvement in the end. My apologies if I came across as trying to trample the design workflow!

Let’s note that somewhere like in some general how-Snowdrift-uses-GitLab reference doc

For the record I reconciled the things that were very clearly not being used like from the outreach repo [doing]. The outreach also had a redundant [blocked] label which I removed after attaching the group [blocked] label to the two issues which had those (now removed) project labels. I also removed the (also unused) group project label “newcomer”, and promoted the snowdrift (subgroup) repo label [newcomer-friendly] to a group label.
There are probably trivial details, and shouldn’t affect anything, but wanted to document them just in case.

and I believe @wolftune deleted the snowdrift subgroup label [operations] because there was only one issue attached to it (which was moved to the ops repo)

These were trivial instances which was why I went ahead with them. Otherwise I would definitely want consensus from all affected parties/repos!

All right. Initially I had read one of the aims in your proposal as consolidating most or ideally all of the project labels to group level.

It goes back to your point about making it clear which group(? maybe project?) a label belongs to. In the label assignment menu on an issue page, it’s not apparent to people outside of the domain which labels are group or project level while opening a new issue. The label description does not appear when hovering over the label in the menu. People might presume “ready” was part of the same structure as the “doing” and “do next” labels, which were set up for a different purpose. So there is more varied group-level filtering, while the existing labels would probably need revising if making the distinction between project/group labels is still an objective.

Sorry, I don’t quite understand how the two are linked, can you please elaborate?

To clarify, I don’t often add new labels, usually leaving it to the team leads to do whatever they find intuitive. They/PMs know what skills are needed for a given issue, will triage and label accordingly. Sometimes I might rename or trim keep them short and stylistically consistent if applicable, or more recently, to align with a group-level proposal.

Not sure if it answers your question, but I would prefer not the change the design labels if it requires adding project labels that aren’t helpful to the team.

Maybe there is some benefit to identifying some of the generic labels as-is, after seeing how they’re used within the repos and asking whether other teams might also find them useful as part of a template set.

The reason I haven’t pushed aspect-type labels in design to group level is the possibility of cluttering the global list with labels that nobody else uses, and they show up in the label assignment menu for all repos (for users who like to browse from the list rather than search). Second, over time, if no new related issues enter the tracker (e.g. they turned out to be one-time setups), people forget why some labels were promoted. The role maintaining the list then has to check with all teams to verify whether they still want to use the labels, whereas it is simpler in the long term (as the organisation scales up) for teams to decide internally which labels they keep/remove.

That’s about it for my input. I’m inclined to agree with the general points in the presentation that @chreekat linked in the previous topic, one being tools can become a distraction. Decide what you want to accomplish in grooming, then use labels and other means to track them.

2 Appreciations