Overview

We would like to have a standard set of labels available in every repo so that it’s easier to:

groom issues in a standard way
organize issues on a board across different repositories
find issues applicable to beginners/newcomers

We need to agree on two things:

Where to store the cross-repo labels
Which cross-repo labels to start out with (can always be expanded later)

note

Note: In addition to the cross-repo labels proposed here, repositories will still be able to define their own local labels in the old way (the GitHub repo settings UI). Those labels will not be affected unless they conflict with the cross-repo label names.

Current state

In GitHub’s architecture, labels are managed per-repo, so it takes some work to synchronize them across repos.

We currently keep cross-repo labels in ~~three~~ four places:

GitHub’s org-wide default labels.
- Unfortunately, these only apply to new repos. Updating them will not fix labels any existing repo. As such, most repositories do not have all the labels listed there.
- Also unfortunately, there does not seem to any programmatic way to query or update these default labels. This means that org-wide default labels cannot be kept in sync with repos, so this path is a dead end for us.
The EnsureLabels repo check which, when run, ensures that a defined set of labels exist across many repositories. So far, this has been working well for us.
- The check is smart: if a label exists in a repo with slight differences (different casing, missing or extra emoji/spaces/dashes, different color), the label will be updated to match the version in the repo check.
- However, it doesn’t sync label descriptions, although that’d be easy to fix.
- The set of labels is hard-coded into repo_checks, so it is pretty hard to find for anyone who isn’t in the know.
The OSPR bot’s labels.yml file. The bot has historically added these labels, as needed by the OSPR workflow.
- The file is in a private repo.
- It’s not clear which labels are used, or if the OSPR bot even still manages labels.
The DEPR automation workflow, which specifically adds the DEPR label to a repository if it’s missing.

1. Proposal: Store labels in one central place

note

This will be implemented by: https://github.com/openedx/terraform-github/pull/60

Remove extraneous sources of cross-repo labels.
1. Delete all the repository default labels from the openedx org’s settings.
2. Remove the labels from the OSPR bot repo.
3. Remove the DEPR automation step that adds the DEPR label.
Add support for syncing label “descriptions” to EnsureLabels This should be very easy.
Either:
1. Store the labels in a new labels.yml file in the same directory as repo_checks.py. Change EnsureLabels to pull labels from the json file.
  - Going forward, cross-repo labels would be managed by editing labels.json and re-running EnsureLabels.
2. Change EnsureLabels to pull the labels via the API from one central repository: .github.
  - Going forward, cross-repo labels would be managed by editing the labels via the repo settings of .github and re-running EnsureLabels.
  - The benfit of this is that it’d be easier for non-coders to manage cross-repo labels. The drawback of this is that changes to our cross-repo labels would not be version-controlled.
Add a step to tCRIL’s “new repository” playbook: Execute repo_checks so that the new repository’s setting matches our standards, including its list of labels.

2. Proposal: List of starter labels

note

This will be implemented by: https://github.com/openedx/terraform-github/pull/61

Name	Description – one brief line that will be shown in the GitHub UI Notes are in italics
good first issue	Good for newcomers
help wanted	Ready to be picked up by anyone in the community
🗺️ epic	Large unit of work, consisting of many tasks
🌎 initiative	Huge unit of work, consisting of multiple epics
maintenance	Work that must be done for platform health
bug	Something isn't working
discovery	Pre-work to determine if idea is feasible
enhancement	Update or improvement to an existing feature
~~question~~	~~Further information is requested from the author~~ Deleted as it seems that this is no longer used for intended purpose (indicating that the triager has a question for the author). Some issues use it to indicate “discovery” but we should just use the discovery label for that. We can always add this label back later.
~~requirement~~	~~Condition that must be met for a project or MVP~~ I’ve removed this from the list as it seems unused.
feature	Addition of new functionality
DEPR	Proposal for deprecation & removal. See OEP-21
wontfix	This will not be worked on
duplicate	This issue or pull request already exists
waiting on author	PR reviewers are waiting on the author to answer questions, fix tests, etc. Waiting for the author to respond to change requests, feedback, failing tests, etc. Usually this label is used for PRs in board statuses other than “Waiting for Author” (e.g. the pull request is “In Eng Review” column on the board, but the author needs to address review feedback).
inactive	PR author has been unresponsive for several months Used when the author has been unresponsive for several months. Typically author will be told “we might need to close this due to inactivity” and if there’s still no response we close it a couple weeks later.
closed-inactivity	PR was closed because the author abandoned it Closed due to PR being abandoned. Typically used after a PR has been abandoned and labeled as “inactive.”
needs test run	Author’s first PR to a repository, awaiting test authorization from tCRIL This means an author has not contributed to a particular repo before and needs authorization to be able to run tests on the PR. Currently, test authorization is handled by tCRIL.
core contributor	PR author is a Core Contributor to this repository (manually added) Currently manually applied on the Contributions board to flag to project managers that a CC is the author.
open-source-contribution	PR author is not from tCRIL or 2U Automatically added by bot to PRs coming from the community (not tCRIL or 2U).
blocked by other work	PR cannot be finished until other work is complete Notating that the PR is blocked. It should say in the PR why the work is blocked (e.g. waiting to merge a related PR first).
~~changes requested~~	~~PR reviewers are waiting on author to apply feedback~~ ~~A reviewer or reviewers have taken a look at the PR and requested the author make changes.~~ Deleting; we will use “Waiting on Author” instead. We should notify Michelle and Tim when this change happens so that they can update the board.
product review	PR requires product review (= it won’t be merged without review and approval from a product manager). Jenna Makowski / Ryan O’Connell will add this label to PRs labeled “open-source-contribution” that require Product Review.

Reference: Current cross-repo labels

Repo defaults, from openedx org settings:

Open edX Community > openedx org-wide labels > image-20230306-172017.png

Ensured labels, from repo_checks.py:

        {   
            ":hammer_and_wrench: maintenance": "169509",
            "waiting on author": "bfd6f6",
            "inactive": "ff950a",
            "closed-inactivity": "dbcd00",
            "needs test run": "f5424b",
            "good first issue :tada:": "43dd35",
        }

Labels added by the OSPR bot:

architecture review:
    # Not used currently 
    color: ffb6c1
awaiting prioritization:
    color: b7e687
blocked by other work:
    color: ffa500
changes requested:
    color: 76a4e3
community manager review:
    color: ffea45
engineering review:
    color: 90d946
merged:
    color: 056608
needs triage:
    color: b7b7b7
open edx community review:
    color: 00a7a7
product review:
    color: c97bf7
rejected:
    color: a9a9a9
waiting on author:
    color: bfd6f6


# Other Labels (can be added independently from statuses)

blended:
    color: 6b360f
cc-reviewer:
    color: 5aa17f
core committer:
    color: aaf0d1
open-source-contribution:
    color: f0f0f0