ADR Suggestion, Unified Labeling System for EasyScience GitHub Organization

[AndrewSazonov]

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:

1. Use GitHub's default labels as a base, ensuring familiarity for contributors.
2. Add two additional labels (maintenance and significant) to account for specific project needs.
3. Modify descriptions slightly to align with our workflows and to provide clear guidance on semantic versioning impacts (major.minor.patch).

---

Default GitHub Labels

The following are GitHub’s default labels, which will form the foundation of the new labeling system:

Label	Color code	Default description	Description from Managing labels
bug	#d73a4a	Something isn't working	Indicates an unexpected problem or unintended behavior.
documentation	#0075ca	Improvements or additions to docs	Indicates a need for improvements or additions to documentation.
duplicate	#cfd3d7	This issue already exists	Indicates similar issues, pull requests, or discussions.
enhancement	#a2eeef	New feature or request	Indicates new feature requests.
good first issue	#7057ff	Good for newcomers	Indicates a good issue for first-time contributors.
help wanted	#008672	Extra attention is needed	Indicates that a maintainer wants help on an issue or pull request.
invalid	#e4e669	This doesn't seem right	Indicates that an issue, pull request, or discussion is no longer relevant.
question	#d876e3	Further information is requested	Indicates that an issue, pull request, or discussion needs more information.
wontfix	#ffffff	This will not be worked on	Indicates that work won't continue on an issue, pull request, or discussion.

---

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

Label	Color code	Description
bug	#d73a4a	Something isn’t working. Applies to issues or pull requests that fix the problem, typically bumping the patch version (major.minor.PATCH).
documentation	#0075ca	Improvements or additions to documentation, typically bumping the patch version (major.minor.PATCH).
duplicate	#cfd3d7	This issue or pull request already exists.
enhancement	#a2eeef	A request or implementation of a new feature or improvement, typically bumping the minor version (major.MINOR.patch).
good first issue	#7057ff	Issues that are suitable for newcomers or first-time contributors.
help wanted	#008672	Tasks requiring additional input or support from contributors.
invalid	#e4e669	Issues or pull requests that are invalid, incorrect, or no longer relevant.
question	#d876e3	Further information or clarification is required.
maintenance	#25f535	Changes to code structure, build processes, tooling, or dependencies that neither fix a bug nor introduce new features, typically bumping the patch version (major.minor.PATCH).
significant	#d93f0b	Major changes that may break current functionality or introduce backward incompatibility, typically bumping the major version (MAJOR.minor.patch).
wontfix	#ffffff	Work will not continue on this issue or pull request.

[damskii9992]

A small comment: I would not bump the version at all for documentation labels.
Other comments, mostly to spark discussion:
Do we not want labels to clarify the subject of the issue/pull request?
I.e.: Borg, minimizers, API, CI etc.?
Otherwise I wholly agree with this label standardization and the extended description and use of the labels.

[rozyczko]

Do we not want labels to clarify the subject of the issue/pull request? I.e.: Borg, minimizers, API, CI etc.?

I think we can still create project-specific labels, which can be additional to the general labels described above.

[AndrewSazonov]

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.

[rozyczko]

I am not sure adding a project-specific label like borg in EasyScience would make the workflow inconsistent.
This assumes we also mark the PR with the correct labels as described above.

An example would be tasks/PRs related to polarized diffraction. New features would be labeled as enhancements, bugs as bugs etc.
However, adding a custom label polarized will enable filtering all the tasks/PRs for that topic, which could be beneficial for seeing the progress of the (possible) Polarized Diffraction epic in the project board.

An alternative would be to have task names and PRs include the custom label in the task name.