fix(labels): make lib/labels.yml the only canonical label file#471
Merged
Conversation
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.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR eliminates label-definition drift by removing the stale .github/lib/labels.yml file and repointing all in-repo documentation to the single canonical label source at lib/labels.yml, matching what scripts/labels-sync.rb already consumes by default.
Changes:
- Update runbooks and agent instructions to reference
lib/labels.ymlas the sole source of truth. - Fix
.github/README.mdto link to the root canonical label file. - Delete the stale
.github/lib/labels.ymlfile to prevent future silent mis-edits.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| runbooks/triage.md | Updates triage instructions to reference the canonical lib/labels.yml. |
| runbooks/labels.md | Updates label maintenance runbook to use lib/labels.yml consistently. |
| AGENTS.md | Repoints agent guidance to the canonical label source. |
| .github/README.md | Fixes label-file references/linking from within the .github/ directory. |
| .github/lib/labels.yml | Removes the stale duplicate label-definition file. |
ss-o
added a commit
to z-shell/wiki
that referenced
this pull request
Jul 21, 2026
…#802) The page linked z-shell/.github/.github/lib/labels.yml, a stale duplicate removed in z-shell/.github#471. The canonical file, and the one labels-sync.rb reads, is lib/labels.yml at that repository's root. Supports z-shell/.github#461.
This was referenced Jul 21, 2026
ss-o
added a commit
to z-shell/wiki
that referenced
this pull request
Jul 22, 2026
main links to z-shell/.github/.github/lib/labels.yml, which became a 404 when that duplicate was removed in z-shell/.github#471. The corrected link already exists on next via #802, but main requires branches to be up to date and its required Trunk Check fails on this 404, so the promotion that would carry the fix is blocked by the fix's absence. Applies the same one-line correction directly to main to break that deadlock. Identical to the change already on next, so the branches converge cleanly. Co-authored-by: Sall <ss-o@users.noreply.github.com>
ss-o
added a commit
to z-shell/wiki
that referenced
this pull request
Jul 22, 2026
* docs(zsh-lint): add generated-reference markers (#755) docs(zsh-lint): add generated-reference markers and seed content Re-add the {/* zsh-lint:generated:start/end */} markers to the Zsh Lint ecosystem page so the wiki-docs-sync pipeline from z-shell/zsh-lint has a region to inject into. Seed the region with the current generated Go reference so the first automated sync is a no-op rather than a failure. The marked region is machine-managed — do not hand-edit; it is regenerated from the repo's Go doc comments. Co-authored-by: Salvydas Lukosius <ss-o@users.noreply.github.com> * docs(zsh-lint): sync generated reference (#756) docs(zsh-lint): sync generated reference from zsh-lint * ci(trunk): fix duplicate Trunk Check context blocking PRs (#759) ci(trunk): rename workflow/job to Trunk Code Quality to fix duplicate check context The workflow and job were both named 'Trunk Check', colliding with the check that trunk-io/trunk-action posts (also 'Trunk Check'). Two identically-named check-runs confuse strict branch protection (required context 'Trunk Check'), leaving PRs stuck in BLOCKED even when all checks pass. Renaming to the org-conventional 'Trunk Code Quality' (matching other repos) leaves the action's 'Trunk Check' as the sole required context. Fixes #757. Co-authored-by: Salvydas Lukosius <ss-o@users.noreply.github.com> * docs(packages): drop removed Zsh 5.1.1/5.2.4 from version list The zsh package no longer ships 5.1.1 or 5.2.4 as selectable profiles (z-shell/zsh#14). Remove the two stale 'zi pack' examples so the usage page matches the available manifest profiles. * docs(zsh-lint): move tool documentation into community * docs(zsh-lint): normalize generated reference indentation * ci(workflows): enforce concurrency and permissions rules * ci(workflows): enforce top-level policy blocks * chore(repo): reconcile main content into next * docs(community): align project metadata with Linear * docs(contributing): point the label source of truth at lib/labels.yml (#802) The page linked z-shell/.github/.github/lib/labels.yml, a stale duplicate removed in z-shell/.github#471. The canonical file, and the one labels-sync.rb reads, is lib/labels.yml at that repository's root. Supports z-shell/.github#461. --------- Co-authored-by: Salvydas Lukosius <ss-o@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #461.
The drift
Two canonical label files existed. Every document pointed at one; the tooling read the other.
lib/labels.yml.github/lib/labels.ymllabels-sync.rbDEFAULT_LABELS_FILE)labels,legacy_migrations,sync_policyTwo corrections to the issue as filed
.github/lib/labels.ymlhard-errors —labels file must contain a mapping— because the schema is incompatible. The genuinely silent path is narrower and is the one that matters: a maintainer followsrunbooks/labels.md, edits the.githubcopy, runs the script with defaults, and the edit is ignored with no error.0644, not0600; the.githubcopy was0664. No permission change was needed.Consumer audit (step 1 of the issue)
Swept every file with a label-related path across all 86 active repositories via the trees + contents API — not code search, which is unreliable here.
No automation anywhere in the organization reads either file. Findings:
.github/workflows/sync-labels.yml, but they callz-shell/.github/.github/workflows/sync-labels.yml@main, which does not exist (404). They never read the label file. Tracked separately.z-shell/src/scripts/sync-labels.shdoes not reference it.z-shell/wiki, repointed in a separate PR.Why delete rather than symlink
The issue offered a symlink. That would be worse: GitHub's raw endpoint returns a symlink's target path as text rather than file contents, so any raw-URL consumer would silently receive
../../lib/labels.ymlinstead of YAML. A clean removal with repointed references fails loudly instead.Verification
labels-sync.rbresolves its default filetest-labels-dry-run.sh../lib/labels.ymlresolves from.github/README.md