Skip to content

LABELING.md

Latest commit

 

History

History
360 lines (258 loc) · 14 KB

LABELING.md

File metadata and controls

360 lines (258 loc) · 14 KB
title Labeling Strategy & Governance
description Label taxonomy, automation rules, and governance for LightSpeed repositories.
file_type documentation
version v1.0.1
author LightSpeed Team
maintainer LightSpeed Team
owners
lightspeedwp
tags
labels
automation
governance

GitHub Labelling & Automation

This document describes how LightSpeed uses GitHub labels to power automation, search, workflow routing, and community management across all repositories—including issues, pull requests (PRs), and discussions.

Table of Contents

  1. Purpose & Principles
  2. Label Categories & Families
  3. Issue Labelling
  4. Pull Request Labelling
  5. Discussion Labelling
  6. Automation & Agent Integration
  7. Best Practices
  8. Troubleshooting

Purpose & Principles

  • Clarity & Automation: Labels provide high-signal metadata for automation, project boards, and contributors.
  • Consistency: All repositories follow a shared, canonical taxonomy (see .github/labels.yml).
  • Discoverability: Labels make it easy to filter, search, and report on work across code, docs, and community.
  • Community Engagement: Dedicated labels for discussions and non-code topics ensure inclusive collaboration.
  • One-hot principle: Only one value per label group (e.g., one priority:*, one status:*).

Label Categories & Families

All canonical labels use a family prefix. The organisation recognises the following label families:

Status Labels (status:*)

Indicate the current progress or state of an issue or PR:

  • status:needs-triage — New, not yet reviewed
  • status:ready — Clear requirements, ready to work
  • status:in-progress — Someone is actively working
  • status:needs-review — Waiting for review/approval
  • status:blocked — Blocked by another issue or dependency
  • status:done — Completed and closed
  • status:wontfix — Intentionally closed as not actionable

Rule: Each issue and PR has exactly one status:* label.

Priority Labels (priority:*)

Indicate urgency and scheduling priority:

  • priority:urgent — Security issue, critical bug, or blocker
  • priority:high — High-impact, affecting multiple users
  • priority:normal — Standard feature or improvement (default)
  • priority:low — Nice-to-have, deferred work

Rule: Each issue and PR has exactly one priority:* label.

Type Labels (type:*)

Classify the nature of the work:

  • type:bug — Unexpected behavior or error
  • type:feature — New functionality
  • type:improvement — Enhancement to existing functionality
  • type:chore — Maintenance, cleanup, tooling, or refactoring
  • type:docs — Documentation improvements
  • type:test — Test suite additions or fixes
  • type:refactor — Code quality improvements, no behaviour change
  • type:performance — Performance optimisation
  • type:security — Security-related changes
  • type:a11y — Accessibility improvements
  • type:design — Design-related work
  • type:release — Release-related tasks

Rule: Each issue and PR has exactly one type:* label. For PRs, it's automatically assigned from the branch prefix; for issues, it's assigned from issue templates or manually.

Area & Component Labels

Area labels (area:*): Indicate the high-level system or domain:

  • area:ci — CI/CD pipelines and automation
  • area:dependencies — Package and dependency management
  • area:documentation — Docs, guides, examples
  • area:quality — Quality validation and QA controls
  • area:a11y — Accessibility standards
  • area:performance — Performance optimisation
  • Other areas as needed

Component labels (comp:*): For WordPress-specific or product areas:

  • comp:block-editor — Gutenberg editor integration
  • comp:block-json — Block JSON schema
  • comp:theme-json — Theme JSON features
  • comp:templates — Template system
  • comp:patterns — Block pattern library
  • Others as relevant to your projects

Rule: At least one area:* or comp:* label per issue/PR.

Context Labels

Provide additional context:

  • Environment: env:production, env:staging, env:development
  • Compatibility: compat:php7, compat:wp6.0, compat:js-es6
  • Phase: phase:1, phase:2, etc. (for multi-phase projects)
  • Device/Platform: device:mobile, device:desktop
  • Language/Locale: lang:en, lang:de, etc.
  • Others as defined per project

Meta & Release Labels (meta:*, release:*)

For release hygiene and workflow signals:

  • meta:needs-changelog — Requires a CHANGELOG.md entry (enforced on PRs)
  • meta:no-changelog — Explicitly no changelog needed (internal-only changes)
  • meta:has-pr — Issue has a linked PR
  • meta:no-issue-activity — No activity for 30+ days
  • meta:stale — Marked for cleanup/archival
  • meta:dependabot-security — Security update from Dependabot
  • release:patch — Patch version bump required
  • release:minor — Minor version bump required
  • release:major — Major version bump required
  • release:hotfix — Hotfix release required

Rule: Never apply both meta:needs-changelog and meta:no-changelog on the same PR.

Contributor & Community Labels

Contributor labels (contrib:*):

  • contrib:good-first-issue — Suitable for new contributors
  • contrib:help-wanted — Needs community input or volunteers
  • contrib:discussion — Topic for community discussion

Discussion labels (discussion:*):

  • discussion:community — Social, networking, or open-ended topics
  • discussion:showcase — User projects, demos, "Show & Tell"
  • discussion:announcement — Official news and team updates
  • discussion:feedback — Suggestions, UX feedback, ideas
  • discussion:support — Help requests, troubleshooting (non-bug)
  • discussion:sponsorship — Funding, GitHub Sponsors
  • discussion:partnership — Collaboration, business, outreach

Issue Labelling

Required Labels per Issue

Every issue must have:

  • One status:* (e.g., status:needs-triage, then progressing to status:ready, status:in-progress, etc.)
  • One priority:* (e.g., priority:normal)
  • One type:* (e.g., type:bug, type:feature)
  • At least one area:* or comp:* (e.g., area:ci, comp:block-editor)
  • Contextual labels as needed (phase:6, meta:needs-changelog, contrib:good-first-issue)

Application Methods

  • Automated: Issue templates auto-assign initial labels (type:*, priority:*, status:needs-triage)
  • Manual curation: Triage and maintainers adjust labels as issue status changes or scope evolves
  • Labeler rules: .github/labeler.yml can auto-apply labels based on file paths, branch prefixes

Automation & Enforcement

  • The unified labeling agent enforces one-hot rules (exactly one status, one priority, one type)
  • The agent removes non-canonical labels or migrates them to canonical equivalents
  • Project board auto-triage uses status labels to organize work
  • Changelog and release labels (meta:needs-changelog, release:*) drive release automation

Pull Request Labelling

Required Labels per PR

Every PR must have:

  • One status:* (automatically set to status:needs-review on open)
  • One type:* (automatically matched from branch prefix: feat/ → type:feature, fix/ → type:bug, etc.)
  • One priority:* (derived from branch prefix or set manually; defaults to priority:normal)
  • At least one area:* or comp:*
  • Release label: release:patch, release:minor, or release:major (required for shipping PRs)
  • Meta labels: meta:needs-changelog or meta:no-changelog (enforced; cannot have both)

Branch Prefix Mapping

PR branch names automatically assign type:* labels:

Core prefixes:

  • feat/ → type:feature
  • fix/ → type:bug
  • hotfix/ → type:bug + release:hotfix
  • refactor/ → type:refactor
  • perf/ → type:performance
  • docs/ → type:docs
  • test/ → type:test
  • chore/ → type:chore
  • ci/ → type:chore + area:ci
  • deps/ → type:chore + area:dependencies
  • security/ → type:security
  • a11y/ → type:a11y
  • build/ → type:chore

Optional prefixes (as needed for your projects):

  • proto/, ds/, api/, schema/ — Product/design system
  • content/, seo/, config/, migrate/ — Client/project specific

Changelog Policy

  • User-facing changes must have meta:needs-changelog (a CHANGELOG.md entry is required for merge)
  • Internal-only changes (refactoring, testing, CI) can use meta:no-changelog to skip changelog requirement
  • Never apply both meta:needs-changelog and meta:no-changelog on the same PR

Automation & Enforcement

  • Labeler automatically applies labels based on branch name and file changes
  • Changelog validation blocks merges if a user-facing PR lacks a changelog entry or required label
  • Status transitions follow one-hot rules (only one status at a time)
  • Release labels guide automated changelog compilation and semantic versioning

Discussion Labelling

Purpose

Discussion labels organize community conversations by topic, making it easy for users to find relevant threads and for moderators to filter and prioritize.

Available Labels

  • discussion:community — Social, networking, or open-ended topics
  • discussion:showcase — User projects, demos, "Show & Tell"
  • discussion:announcement — Official news and team updates
  • discussion:feedback — Suggestions, UX feedback, general ideas
  • discussion:support — "How do I…" setup, troubleshooting, help requests (non-bug)
  • discussion:sponsorship — Funding, GitHub Sponsors, financial topics
  • discussion:partnership — Collaboration, business, outreach

Best Practices

  • Encourage users to select a label when starting a new discussion
  • Apply or update labels when moderating to keep threads organized
  • Use labels to filter discussions when reviewing or responding
  • A discussion can have multiple labels if it spans categories

Automation & Agent Integration

Unified Labelling Agent

All labelling, status enforcement, type assignment, and standardisation are handled by the unified labelling agent (scripts/agents/labeling.agent.js) and labelling workflow (.github/workflows/labeling.yml).

How it works:

  1. Triggered on issue/PR creation, edits, and label changes
  2. Reads canonical configuration from .github/labels.yml, .github/labeler.yml, and .github/issue-types.yml
  3. Applies automatic labels based on:
    • Branch prefixes (PRs only)
    • File path changes
    • PR body front matter
    • Content heuristics
  4. Enforces one-hot rules (exactly one status, priority, type)
  5. Removes non-canonical labels and migrates legacy labels
  6. Generates reports for monitoring and debugging

Agent Utilities

The agent orchestrates reusable utility modules in scripts/agents/includes/:

Utility Responsibility
label-lookup.js Fetch canonical labels, build alias maps, find standard labels
labeler-utils.js Apply labeler rules based on file/branch patterns
label-sync.js Sync repository labels with canonical configuration
status-enforcer.js Enforce one-hot status, priority, type labels
label-reporting.js Build labelling and standardisation reports
type-lookup.js Load issue types and find matches from titles/bodies
label-heuristics.js Suggest labels from issue/PR content

Configuration Files

  • .github/labels.yml — Canonical label definitions, colours, and aliases
  • .github/labeler.yml — File/branch-based label rules
  • .github/issue-types.yml — Canonical issue type definitions

All automation reads from these files; there is no hardcoded label logic in agents or workflows.

Best Practices

  1. Keep exactly one status:* and priority:* on every issue/PR.
  2. Use the most specific area:* or comp:* for filtering and reporting.
  3. Update labels as work progresses or if scope changes.
  4. Trust automation: Let the labelling agent handle most label application; only manually adjust when needed.
  5. Refer to .github/labels.yml as the source of truth for canonical labels.
  6. Use discussion labels to keep conversations organised and welcoming.
  7. Review and clean up labels quarterly, removing unused or redundant entries.
  8. Always provide meta:needs-changelog or meta:no-changelog on PRs before merging.

Troubleshooting

Missing or incorrect labels?

  • Check .github/labels.yml for missing/typo entries
  • Verify branch prefix or file pattern matches in .github/labeler.yml
  • Run node scripts/agents/includes/check-template-labels.js to validate issue/PR templates

Label not applied as expected?

  • Review labeler workflow logs in the PR/issue activity
  • Check if the labelling workflow is enabled and up-to-date
  • Verify the labelling agent has access to read/write labels

Want to add a new label or modify rules?

  1. Update .github/labels.yml with the new canonical definition
  2. Update .github/labeler.yml if you need automatic application rules
  3. Update this documentation to describe the new label
  4. Create a PR and reference this issue #636

Non-canonical labels appearing?

  • The labelling agent automatically migrates old labels to canonical equivalents
  • If a label persists, check .github/label-governance-policy.yml for exceptions
  • Open an issue if a label should be migrated or removed

References