ADR Suggestion Extend ADR #33 (Unified Labeling System)

[AndrewSazonov]

In ADR #33 - Unified Labeling System, four standardized label groups were defined to simplify and unify issue and pull request management across the EasyScience organization.

This ADR suggestion is opened to document recent changes that were not yet captured in ADR #33, and to propose a small extension to the labeling system for automated pull requests.

Changes to [scope] documentation

The description of the label [scope] documentation has been updated.

Old description:

Documentation only changes (major.minor.patch-EXTENSION)

New description:

Documentation only changes (major.minor.patch.POST)

This means that a merged PR labeled with [scope] documentation should now result in a version bump like X.Y.Z.postN, instead of using -EXTENSION.

The reason for this change is that .post versions increase the package version as expected, while using a suffix like -EXTENSION actually result in a lower version according to Python versioning rules, which is not what we want.

New label: [bot] pull request

To clearly distinguish automated pull requests from human-authored work, a new label is proposed:

• Label: [bot] pull request
• Color: #5319e7 (violet)
• Description: Automated release PR. Excluded from changelog/versioning

This label belongs to a new unified group:

[bot] labels group

Description:

• This group is unified across all EasyScience projects.
• Labels in this group are applied automatically by bots or automation workflows.
• Indicate system-generated actions, such as automated release PRs, dependency updates, maintenance or synchronization tasks.
• Optional. Applied automatically.

This makes automated activity explicit and easier to filter.

Label update scripts

Option 1: Existing bash script (current approach)

We already have an existing bash script in easyscience/tools:

https://github.com/easyscience/tools/blob/master/unified_labels.sh

This script works well for applying unified labels across the organization.

Pros:

• Already exists and proven to work

Cons:

• Must be run locally
• Not very cross-platform friendly
• Runs for the whole organization, which is slow and not always needed
• Limited flexibility (no dry-run, no easy per-repository targeting)

Option 2: Python script in Copier templates (experimental / incremental)

A Python-based script was added to the Copier templates, mainly as an experiment, to avoid running the bash script for the whole organization every time and to safely test new or updated labels on individual repositories only:

https://github.com/easyscience/templates/blob/master/template/tools/update_github_labels.py

The script is intended to be run via a Pixi task and can target:

• the current repository, or
• a user-specified repository

It supports a --dry-run mode to preview the commands that would be executed, without applying any changes.

Pros:

• Cross-platform
• More flexible than the bash script
• Supports dry-run
• Well suited for testing and gradually rolling out new labels
• Easier to extend and maintain over time

Cons:

• Lives in templates, not in a centralized tools repository
• Exists alongside the original bash script, which causes duplication

Option 3: Centralized, CI-based solution (proposed next step)

Given the higher flexibility and maintainability of the Python approach, a possible next step would be to extend it with an option to update all repositories in the organization, move it to easyscience/tools, and add a workflow to expose it via a GitHub Action using workflow_dispatch.

Such a workflow could allow:

• running label updates:
  • for the whole organization, or
  • for a single repository

In this case, the same tool could be run either locally as a cross-platform solution or remotely via GitHub Actions.

[damskii9992]

Changes to [scope] documentation

This change was already implemented, albeit silently. So I guess its good to have it documented in a discussion here and linked to in #33 when this discussion is closed.

[bot] labels group

Makes sense. No notes. Which tags do you foresee to exist in this group, on top of [bot] pull request?

Label update scripts

The bash script was a quick and easy solution, better ideas are more than welcome. I simply didn't want to waste time on making a more robust / maintainable solution for a script we will rarely ever run. If you feel inclined to do so, you're more than welcome.

[rozyczko]

Combine Option 2 with Option 3 (python script which should be able to run for the entire org as well) needs to go to the Copier Template setup as a separate script.
A user can use it for a separate repository
On the org level, one can run the workflow (on dispatch) running the combined script.