From 1641fd414d65724d8f96fad07668b73984fccc5d Mon Sep 17 00:00:00 2001 From: Sall Date: Wed, 22 Jul 2026 00:22:07 +0100 Subject: [PATCH] fix(labels): make lib/labels.yml the only canonical label file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #461. Two canonical label files existed and had diverged. Every document pointed at .github/lib/labels.yml; scripts/labels-sync.rb reads lib/labels.yml. A maintainer following runbooks/labels.md edited the copy the tooling never reads, and nothing reported the mistake. The two were not equal authorities. Root holds 32 labels plus the legacy_migrations and sync_policy blocks; the .github copy was a bare YAML array of 29 labels with neither block, a strict subset and an incompatible schema — labels-sync.rb rejects it outright with 'labels file must contain a mapping'. It also still described meta:org-tracked in terms of the retired GitHub Projects tracker. Removes the stale copy and repoints all seven references. The .github README link needed ../lib/labels.yml, being relative to .github/. A consumer audit found no automation reading either file anywhere in the organization; the only external reference is a documentation link in z-shell/wiki, repointed separately. The 33 repositories carrying sync-labels.yml call a reusable workflow that does not exist and never read the label file; that is tracked on its own. --- .github/README.md | 4 +- .github/lib/labels.yml | 94 ------------------------------------------ AGENTS.md | 2 +- runbooks/labels.md | 8 ++-- runbooks/triage.md | 2 +- 5 files changed, 8 insertions(+), 102 deletions(-) delete mode 100644 .github/lib/labels.yml diff --git a/.github/README.md b/.github/README.md index cc6eb1cc4..191157d06 100644 --- a/.github/README.md +++ b/.github/README.md @@ -97,7 +97,7 @@ Starter workflows available in every org repository under **Actions > New workfl | Zsh CI | Starter Zsh CI workflow | | Rclone Action | File sync with rclone | -Label definitions live in [`./lib/labels.yml`](lib/labels.yml) and should be applied through org maintenance scripts or API-driven automation, not via a generic starter workflow template. +Label definitions live in [`lib/labels.yml`](../lib/labels.yml) and should be applied through org maintenance scripts or API-driven automation, not via a generic starter workflow template. Task tracking is documented in [`../runbooks/project-tracker.md`](../runbooks/project-tracker.md). @@ -133,7 +133,7 @@ This repository is the right place for any **organization-level** configuration: - **Defining weekly review, ADR, or release coordination workflows** — add or update the relevant file under `runbooks/` - **Recording cross-agent progress** — follow `.github/AGENT_MEMORY.md` and keep active state in issues, pull requests, and Linear - **Managing organization task tracking** — follow `../runbooks/project-tracker.md` -- **Updating the shared label set** — edit `.github/lib/labels.yml` and roll it out via the org's maintenance automation +- **Updating the shared label set** — edit `lib/labels.yml` and roll it out via the org's maintenance automation - **Cleaning legacy labels** — follow `../runbooks/labels.md` before deleting labels from live repositories - **Creating a reusable CI action** — add a composite action under `actions//action.yml` - **Providing a starter workflow** — add `.yml` + `.properties.json` to `workflow-templates/` diff --git a/.github/lib/labels.yml b/.github/lib/labels.yml deleted file mode 100644 index df9f8e2ab..000000000 --- a/.github/lib/labels.yml +++ /dev/null @@ -1,94 +0,0 @@ ---- -# Canonical organization label definitions. -# Apply these through gh/API-based maintenance automation rather than a starter workflow template. -- name: "type:bug" - color: b60205 - description: "Something is broken or behaving incorrectly." -- name: "type:feature" - color: 0e8a16 - description: "A request for new behavior or capability." -- name: "type:docs" - color: 0052cc - description: "Documentation-only work." -- name: "type:question" - color: d4c5f9 - description: "Support, clarification, or usage question." -- name: "type:maintenance" - color: 531999 - description: "Non-feature maintenance, cleanup, or org work." -- name: "type:membership" - color: 6f42c1 - description: "Membership and organization-role requests." -- name: "type:handoff" - color: 5319e7 - description: "Cross-agent or cross-maintainer handoff context." - -- name: "area:zi" - color: 1d76db - description: "Zi core behavior, APIs, or documentation." -- name: "area:plugin" - color: 3e16f3 - description: "Plugin behavior or plugin-facing work." -- name: "area:annex" - color: 3e16f3 - description: "Annex behavior or annex-facing work." -- name: "area:package" - color: 3e16f3 - description: "Package or package-management work." -- name: "area:docs" - color: 0052cc - description: "Documentation systems, content, or publishing." -- name: "area:ci" - color: 5319e7 - description: "Continuous integration or GitHub Actions work." -- name: "area:dependencies" - color: fbca04 - description: "Dependency updates or dependency-management work." -- name: "area:release" - color: d93f0b - description: "Release process, versioning, or changelog work." -- name: "area:meta" - color: 1d76db - description: "Organization-wide policy, templates, or meta-repo work." - -- name: "priority:high" - color: ee0701 - description: "Needs prompt attention." -- name: "regression" - color: b60205 - description: "Previously working behavior is broken." -- name: "security" - color: ee0701 - description: "Security-sensitive issue or hardening work." -- name: "breaking-change" - color: d93f0b - description: "Breaks backward compatibility or changes a public contract." - -- name: "status:triage" - color: fbca04 - description: "Awaiting initial review or classification." -- name: "status:blocked" - color: e4e669 - description: "Cannot proceed until an external dependency or decision changes." -- name: "needs-info" - color: f9d0c4 - description: "Waiting on more detail before work can continue." -- name: "good first issue" - color: 7057ff - description: "Well-scoped starter task for a new contributor." -- name: "help wanted" - color: 008672 - description: "Maintainers would welcome outside help." -- name: "invalid" - color: 0b467f - description: "Off-topic, incorrect, or not actionable." -- name: "duplicate" - color: cfd3d7 - description: "Covered by another issue or pull request." -- name: "wontfix" - color: ffffff - description: "Acknowledged but not planned for implementation." - -- name: "meta:org-tracked" - color: 5319e7 - description: "Auto-add this issue to the org-wide Z-Shell Tracker." diff --git a/AGENTS.md b/AGENTS.md index 7ed32d64d..62fb7e3f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,7 +86,7 @@ Use `runbooks/triage.md` for the full process. Short version: - Classify issues by work type, area, and severity. -- Use the canonical labels from `.github/lib/labels.yml`. +- Use the canonical labels from `lib/labels.yml`. - Search for prior art across the org before responding. - Put cross-repo, release-blocking, security, or strategic work on Linear. diff --git a/runbooks/labels.md b/runbooks/labels.md index 139c5870d..afe8ed3b9 100644 --- a/runbooks/labels.md +++ b/runbooks/labels.md @@ -4,7 +4,7 @@ Use this runbook when cleaning or syncing labels across z-shell repositories. ## Source of truth -`.github/lib/labels.yml` is the canonical organization label set. +`lib/labels.yml` is the canonical organization label set. Use compact namespace names: @@ -108,11 +108,11 @@ Also retire spaced namespace variants such as `type: bug`, `area: docs`, `priori scripts/labels-sync.rb --all-repos > /tmp/z-shell-labels-dry-run.md ``` -3. Create or update every canonical label from `.github/lib/labels.yml`. +3. Create or update every canonical label from `lib/labels.yml`. 4. For each legacy label, find open issues and pull requests using it. 5. Add the canonical replacement to each item before removing the legacy label. 6. Delete legacy labels only after they are no longer used. -7. Re-run the dry-run audit and compare it with `.github/lib/labels.yml`. +7. Re-run the dry-run audit and compare it with `lib/labels.yml`. Do not delete unknown labels in bulk. If a repository has a local label that is not obviously legacy, open or update an issue before removing it. @@ -180,6 +180,6 @@ scripts/labels-sync.rb \ ## See also -- `.github/lib/labels.yml` +- `lib/labels.yml` - `runbooks/triage.md` - `runbooks/org-review.md` diff --git a/runbooks/triage.md b/runbooks/triage.md index 7975f8765..a733cc7fe 100644 --- a/runbooks/triage.md +++ b/runbooks/triage.md @@ -23,7 +23,7 @@ If classification takes more than a few minutes, mark it for investigation and m ## Step 2 — Apply the canonical labels -The organization label set in `.github/lib/labels.yml` is the source of truth. Apply at least one work-type label and one area label when the area is known. +The organization label set in `lib/labels.yml` is the source of truth. Apply at least one work-type label and one area label when the area is known. ### Work type