EasyScience
ADR Suggestion Unified Labeling System for EasyScience GitHub Organization
#21
Replies: 7 comments 23 replies
-
|
A small comment: I would not bump the version at all for documentation labels. |
Beta Was this translation helpful? Give feedback.
-
I think we can still create project-specific labels, which can be additional to the general labels described above. |
Beta Was this translation helpful? Give feedback.
-
|
While subject-specific labels can seem useful, they may complicate workflows and create inconsistencies. The subject of an issue or pull request can be better captured through the title, description, or milestones, which provide enough flexibility to include detailed, project-specific information. A minimal and standardized label set helps maintain simplicity and consistency across all repositories. Adding project-specific labels would go against the idea of unifying labels because such labels would not be consistent across projects under the EasyScience organization. This could lead to different meanings for similar labels in different projects, causing confusion. To ensure clarity and consistency, it is better to have a single, centralized set of labels that are generic enough to apply to all subprojects. These labels should focus on workflows and actions, while project-specific details can be highlighted in the issue or pull request content or through milestones. By keeping the label set minimal and generic, we can maintain uniformity and avoid unnecessary complexity, while still allowing project-specific details to be expressed in other ways. |
Beta Was this translation helpful? Give feedback.
-
|
I am not sure adding a project-specific label like An example would be tasks/PRs related to polarized diffraction. New features would be labeled as An alternative would be to have task names and PRs include the custom label in the task name. |
Beta Was this translation helpful? Give feedback.
-
|
I don't like the idea of having the custom labels in the task and PR names. |
Beta Was this translation helpful? Give feedback.
-
|
I’d like to add one more comment on why I’m not in favor of using custom labels, especially when it comes to tasks and PR names. If we end up with two groups of labels - one fixed across all projects and another custom for each project - how are we going to maintain this in the long run? GitHub only provides a single label list per repository, and there’s no way to group or nest labels by category or project. Once we start adding custom labels linked to specific functionality (e.g., Over time, this list of custom labels will inevitably grow, especially as new functionality is added. Some of those labels may become outdated or irrelevant - for example, referencing a calculation engine that is deprecated. At that point, someone will have to maintain and clean up the list, which is a non-trivial task. And if the label list grows large enough, it becomes difficult to browse, and people (myself included) might start skipping the step of assigning or using those labels. This would defeat the purpose of having a unified, consistent labeling system in the first place. I suggest we maintain a fixed, generic set of unified labels across all projects in the organization. For simplified filtering of project- or topic-specific tasks, we can use other tools that GitHub Projects already provides. For example:
There are probably other approaches to simplify filtering without introducing project-specific, dynamic labels that risk breaking the consistency of our unified labeling system. I think it’s worth exploring these options rather than complicating label management. |
Beta Was this translation helpful? Give feedback.
-
I don't think we need to maintain this. The idea of local labels is to enable better filtering for a given project. One example would be to have importance label for larger projects with multiple tasks. We would like to assign importance to each story/task in order to better manage the project. Another case would be for things like |
Beta Was this translation helpful? Give feedback.
-
|
Let's take a look at the EasyScience Core Library as an example. You can see its current label list here: https://github.com/easyscience/corelib/labels At the moment, the labels are a mixture of different types:
If we introduce labels like As the list grows, it becomes harder to manage. Every time we want to assign labels to an issue or PR, we need to scroll from the very top to the bottom to find all the relevant labels. As more labels are added (especially project-specific or functionality-specific ones), the label list will inevitably grow and become cluttered. And this is where maintenance becomes a problem. While issue and PR labels are generally fixed (we currently aim for around 10 core labels, potentially with a few more generic ones), labels related to functionality, priority, and other project-specific contexts are dynamic. As projects evolve:
For example, in EasyDiffraction, I can already think of a dozen functional labels we might create today, and the number will only grow. Since GitHub doesn’t allow us to split labels into groups, I’m looking for a workaround that reduces complexity and maintenance effort. My proposal is:
To illustrate, I’ve created a dummy project here: EasyPeasy project This approach gives us:
I believe this strikes the right balance between flexibility for project management and consistency in our core development workflows. |
Beta Was this translation helpful? Give feedback.
-
|
I am not sure adding a complex mechanism of additional custom field is addressing the underlying need. I see the advantage of having a rigid set of labels for important aspects like:
But I do not agree that we should limit the labels for issues/tasks. What I am trying to say is that labels help with easy categorisation of issues and the proposed custom field solution removes the word Prunning the label list for a project can be made a task at the end of each release, just like we remove finished tasks from the project board. |
Beta Was this translation helpful? Give feedback.
-
|
So I decided to look into this because I figured we couldn't possibly be the only ones with this issue, and I found this: Proposed Unified Label Group Set The new unified set includes the default GitHub labels with slight modifications to their descriptions and adds two new labels: maintenance and significant.
In addition to providing these groups of labels we should also enforce their usage:
I am very open to other names for the groups or more groups. |
Beta Was this translation helpful? Give feedback.
-
|
I also prefer using square brackets. They give a clear separation between the group and the label name, which I find much easier to read than slashes or colons. It is visually cleaner and quicker to scan when you’re looking through a long list of labels. About enforcing label usage through workflows: we already have one that makes sure a pull request has at least one label from the version group, since that’s necessary to trigger the right version bump for releases. Do we actually need anything more than that? I feel like all the other labels are optional, especially for issues. What matters most is how PRs are labeled, because they’re directly tied to versioning. And realistically, a PR label won’t always match the label on the related issue (assuming there even was an issue converted to this PR). One issue can lead to several PRs, or vice versa, and they might not have the same scope. So I’m not sure that there’s much value in enforcing strict labeling on issues. Plus, while we can automate label checks for PRs with GitHub workflows, how could we enforce something similar for issues? If the version label is only important for PRs, maybe it makes sense to clearly split labels into “pull request” and “issue” groups. Then there’s no need to overthink whether a label applies to one or the other. Just have groups like The idea of splitting labels for issues and PRs also comes from how some labels don’t quite fit both. For example, in EasyScience corelib, we have a Alternatively, we could stick with Christian’s groupings: |
Beta Was this translation helpful? Give feedback.
-
|
While I unfortunately don't think we can "force" a label on an issue the same way we can on a PR, we can use the action that I linked to, to automatically add the Looking through what I called the I am also in favor of the square brackets and color coding groups. So maybe we should have the following list of groups?
For the priority label group, I think we should have the following labels: |
Beta Was this translation helpful? Give feedback.
-
I agree that if we really want to ensure each issue gets labeled properly and encourage people to follow that process, we need some kind of enforcement. Adding a default like But, since the
I like the
But there’s still the question of cases like the
Personally, I think
Are you suggesting we always apply a |
Beta Was this translation helpful? Give feedback.
-
Yes :) It was just the flow of the comment. And I like adding the warning triangle if we can.
I don't have a strong opinion on this, but this is only an issue for
The action I mentioned is the action I linked to which automatically adds the "label missing" label if the label is missing. |
Beta Was this translation helpful? Give feedback.
-
This looks most correct to me. Labels should be used to categorize the problem they describe, NOT the solution.
This has to be us, maintainers. Users will always assign the highest priority but we need to triage the requests and assign proper importance to them.
I don't like either of them, but
+1 |
Beta Was this translation helpful? Give feedback.
-
|
This is the revised proposal, incorporating the latest suggestions. Please review it carefully and share any additional feedback or comments. Label groups
Label list
Notes
|
Beta Was this translation helpful? Give feedback.
-
|
One more "discovery". GitHub has now Those are like labels, but defined at the organizational level. For us, they are defined here: Then, each issue contains both a field for labels and for types. See for instance easyscience/EasyDiffractionBeta#70 If we specify the types on the organizational level as in Andrew's The only problem is that the |
Beta Was this translation helpful? Give feedback.
-
|
Oh, that’s an important discovery - definitely something we need to take into account for this ADR! It would be ideal if we could define all unified labels (like So, what are our options? Here's how I see it: Option 1Ignore Issue Types for now
Option 2Split the label groups into two sets: Issues and PRs
I tend to prefer Option 2, especially since GitHub itself suggests having a separate group of Issue Types. If (or when) PR types are eventually supported at the organization level, I doubt they will be merged into the existing Issue Types. More likely, GitHub will introduce a separate group specifically for PR types. As we’ve discussed in previous posts, the names and categorizations that work well for issues don’t always translate effectively to PRs and can sometimes lead to confusion. This potential step from GitHub reinforces the idea of keeping them separate. |
Beta Was this translation helpful? Give feedback.
-
|
I think it would be beneficial to use the so, I'm for option 2️⃣ |
Beta Was this translation helpful? Give feedback.
-
|
I think we need to change the currently outlined Option 2, unfortunately, as an issue can only have 1 type, yet our issues will have multiple labels from the different groups, such as |
Beta Was this translation helpful? Give feedback.
-
|
A very important small comment from the discussion Piotr linked to: |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, people are still requesting support for PR types, but without success so far. Here’s a screenshot from the discussion that continued on another page: https://github.com/orgs/community/discussions/148715 
|
Beta Was this translation helpful? Give feedback.
-
|
So, considering the last few posts, should we go with Option 1 - ignore Issue Types for now and delete them from the organization to avoid confusion? |
Beta Was this translation helpful? Give feedback.
-
|
I see the advantages of keeping issue options, but not in the current state. It's probably more prudent to standardize on the labels, however clunky the solution is. |
Beta Was this translation helpful? Give feedback.
-
|
The descriptions in the proposed list of labels will have to be ammended, as the maximum character length of descriptions on GitHub is 100 characters. Offending Labels:
|
Beta Was this translation helpful? Give feedback.
-
|
Here is the updated table with shortened label descriptions (all under 100 characters):
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Each repository within the EasyScience organization currently maintains its own set of labels. These labels are often the default ones created by GitHub when a repository is initialized. However, some repositories have added custom labels (e.g.,
chore,dependencies,Major) with differing descriptions or colors. This inconsistency across repositories makes it difficult to manage issues and pull requests uniformly and creates confusion for contributors.To simplify and unify issue and pull request management, I propose the adoption of a standardized set of labels across all repositories within the EasyScience organization. This unified system will:
Default GitHub Labels
The following are GitHub’s default labels, which will form the foundation of the new labeling system:
#d73a4a#0075ca#cfd3d7#a2eeef#7057ff#008672#e4e669#d876e3#ffffffProposed Unified Label Set
The new unified set includes the default GitHub labels with slight modifications to their descriptions and adds two new labels: maintenance and significant.
#d73a4a#0075ca#cfd3d7#a2eeef#7057ff#008672#e4e669#d876e3#25f535#d93f0b#ffffffBeta Was this translation helpful? Give feedback.
All reactions