Label System Guide

This document describes the standardized labeling system used in this repository for issue and pull request management.

Overview

The repository uses a three-tier labeling system to improve project organization, workflow clarity, and automation effectiveness. Labels are synchronized from .github/labels.yml via the label-sync.yml workflow.

Important: Never edit labels directly in the GitHub UI. Always update .github/labels.yml and let the workflow sync the changes.

Label Categories

Process Labels

These labels trigger specific automation workflows or indicate special handling requirements:

  • Todo - Triggers Copilot automation to draft a fix for the linked issue
  • monitoring - Screeps PTR monitoring alerts raised by automation
  • copilot - Changes or issues generated by GitHub Copilot workflows
  • needs/regression-test - Reports missing coverage; add a regression test before merging

State Labels

Track the lifecycle of issues and pull requests:

  • state/pending - Issues awaiting triage or initial review (default for new issues)
  • state/backlog - Confirmed issues not yet started
  • state/in-progress - Issues currently being worked on
  • state/blocked - Issues blocked by external dependencies or other issues
  • state/canceled - Issues that will not be addressed
  • state/done - Completed issues (alternative to closing)

Best Practice: Update state labels as work progresses to maintain accurate project status.

Type Labels

Classify the nature of the issue or pull request:

  • type/bug - Confirmed defects that require fixes
  • type/feature - New functionality or capability requests
  • type/enhancement - Improvements to existing features or functionality
  • type/chore - Maintenance tasks, refactoring, or housekeeping
  • type/question - Questions or requests for clarification

Note: Every issue should have exactly one type label.

Priority Labels

Indicate urgency and importance for prioritization:

  • priority/critical - Immediate attention required; blocking failures or production outages
  • priority/high - High importance; address as soon as possible
  • priority/medium - Standard priority; address in normal workflow
  • priority/low - Low priority; address when capacity allows
  • priority/none - No specific priority assigned

Best Practice: Apply priority labels during triage to help with sprint planning and capacity allocation.

Domain Labels

Identify the technical area or component affected:

  • automation - Workflow, scripting, or infrastructure automation updates
  • runtime - Screeps runtime behaviour, kernel, or creep orchestration changes
  • documentation - Documentation updates in README, docs/, or developer guides
  • monitoring - PTR stats, health checks, or telemetry
  • dependencies - Dependency updates (often opened by Dependabot)
  • regression - Issues that reoccurred after a previous fix

Note: Issues can have multiple domain labels if they affect multiple areas.

Workflow Labels

Common GitHub patterns for community engagement and issue management:

  • good-first-issue - Good for newcomers to the project
  • help-wanted - Extra attention or assistance needed from the community
  • wontfix - This will not be worked on
  • duplicate - This issue or pull request already exists
  • invalid - This doesn’t seem right or is not applicable

Label Usage Guidelines

For New Issues

Issue templates automatically apply appropriate labels:

  • Bug reports get: type/bug, needs/regression-test, state/pending
  • Feature requests get: type/feature, state/pending
  • Automation issues get: automation, type/bug, state/pending
  • Documentation issues get: documentation, type/enhancement, state/pending

During Triage

The copilot-issue-triage.yml workflow automatically:

  1. Analyzes issue content
  2. Applies appropriate type, priority, and domain labels
  3. Sets state to state/pending or state/backlog
  4. Never automatically applies the Todo label (manual decision)

During Development

Update state labels as work progresses:

  1. state/pending → state/backlog (after triage confirmation)
  2. state/backlog → state/in-progress (when starting work)
  3. state/in-progress → state/blocked (if blocked)
  4. state/in-progress → state/done or close (when completed)

For Pull Requests

Automation workflows apply labels:

  • Copilot Todo PRs get: automation, copilot, type/bug or type/enhancement
  • CI Autofix PRs get: automation, copilot, type/chore, priority/high
  • Dependabot PRs get: dependencies

Examples

Example 1: Critical Bug Report

A production-blocking bug should have:

  • type/bug - It’s a defect
  • priority/critical - Immediate attention required
  • runtime - Affects Screeps runtime
  • needs/regression-test - Needs test coverage
  • state/pending → state/in-progress → state/done

Example 2: Documentation Enhancement

A documentation improvement should have:

  • type/enhancement - Improving existing docs
  • priority/medium - Standard priority
  • documentation - Affects documentation
  • good-first-issue - If suitable for newcomers
  • state/pending → state/backlog → state/in-progress → state/done

Example 3: Feature Request

A new feature request should have:

  • type/feature - New functionality
  • priority/low or priority/medium - Based on importance
  • Domain labels as appropriate (runtime, automation, etc.)
  • help-wanted - If community input is desired
  • state/pending → state/backlog → state/in-progress → state/done

Automation Integration

Copilot Todo Workflow

Issues labeled with Todo trigger automated implementation. The workflow:

  1. Creates a draft PR
  2. Implements the fix incrementally
  3. Updates PR description with progress
  4. Runs tests and marks PR ready for review

Stats Monitor Workflow

PTR monitoring creates issues with:

  • monitoring and copilot (process labels)
  • type/bug (it’s a detected problem)
  • state/pending (awaiting review)
  • priority/* based on severity (critical/high/medium)
  • runtime (affects runtime behavior)

Issue Triage Workflow

New issues are automatically triaged with:

  • Appropriate type/* label based on content
  • Suggested priority/* based on impact
  • Relevant domain labels
  • state/pending for initial state
  • Never automatically applies Todo

Additional Resources