Skip to content

README.md

Latest commit

 

History

History
139 lines (99 loc) · 5.44 KB

README.md

File metadata and controls

139 lines (99 loc) · 5.44 KB
Raw

3DCityDB Labels

GitHub label management system for the 3DCityDB project ecosystem. Maintains consistent issue labels across multiple repositories with automated synchronization and markdown documentation generation.

Managed repositories:

Current labels: See LABELS.md for the full label reference with badge previews, grouped by category.

Prerequisites

  • Python 3
  • pip

Installation

git clone https://github.com/3dcitydb/3dcitydb-labels.git
cd 3dcitydb-labels
pip install -r requirements.txt

Usage

Generate label documentation

Produces a markdown file with shields.io badge previews for all labels, grouped by category.

# Print to stdout
python generate_label_docs.py

# Write to file
python generate_label_docs.py --output LABELS.md

# Use a custom labels file
python generate_label_docs.py --file my-labels.json
Flag Description
--file Path to labels JSON file (default: labels.json)
--output, -o Output file path (default: stdout)

Sync labels to GitHub

Applies labels from labels.json to the configured GitHub repositories via the REST API (v3). By default, only creates or updates labels. Use --remove-all to delete all existing labels before syncing for an exact match with the JSON file.

Token scopes: The access token needs the following permissions:

  • Classic token: repo scope (or public_repo if all target repositories are public)
  • Fine-grained token: read and write on at least one of Issues or Pull requests for each target repository
# Preview changes (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --dry-run

# Sync labels to all repositories
python sync_labels.py --token $GITHUB_TOKEN

# Sync labels to a specific repository
python sync_labels.py --token $GITHUB_TOKEN --repos 3dcitydb/3dcitydb

# Remove all existing labels before syncing (exact match with JSON)
python sync_labels.py --token $GITHUB_TOKEN --remove-all

# Preview remove-all + sync (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --remove-all --dry-run

# Remove all existing labels without syncing
python sync_labels.py --token $GITHUB_TOKEN --remove-only

# Preview remove-only (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --remove-only --dry-run

# Sync to multiple specific repositories
python sync_labels.py --token $GITHUB_TOKEN --repos 3dcitydb/3dcitydb 3dcitydb/citydb-tool

# Use a custom labels file
python sync_labels.py --token $GITHUB_TOKEN --file my-labels.json
Flag Description
--token GitHub personal access token (or set GITHUB_TOKEN env var)
--file Path to labels JSON file (default: labels.json)
--repos One or more owner/repo to sync (default: all repos in JSON file)
--dry-run Show what would change without applying
--remove-all Remove all existing labels from target repos before syncing
--remove-only Remove all existing labels from target repos without syncing

Label name matching is case-insensitive during sync.

Label schema (labels.json)

All label data is defined in a single file, labels.json, which serves as the single source of truth.

Key Description
repositories List of owner/repo strings to sync
groups Label category definitions with name, base_color, and description. Used only for documentation generation — groups are not synced as GitHub labels.
shared_labels Labels applied to all repositories. Each has name, color, description, and group.
repo_labels Map of owner/repo to a list of repository-specific labels (domain tags).

Colors are stored as hex values without the # prefix (e.g., "D62728"). Label names use a hierarchical colon format (e.g., type: bug, domain: schema). Label descriptions must not exceed 100 characters (GitHub API limit).

Label groups

Group Base Color Description
Type #1F77B4 Identifies what kind of work the issue represents
Status #9467BD Shows the issue's current progress state
Priority #D62728 Reflects importance and urgency
Contribution #FF7F0E Related to community participation
Release #17BECF Versioning, regressions, backports
Infrastructure and others #7F7F7F CI/CD and repository maintenance, data, and others
Domain #2CA02C Indicates which subsystem or concept is affected. These tags are different for each repo.

Workflow

  1. Edit labels.json (add/modify labels)
  2. Run python generate_label_docs.py --output LABELS.md to regenerate docs
  3. Run python sync_labels.py --dry-run --token $GITHUB_TOKEN to preview changes
  4. Run python sync_labels.py --token $GITHUB_TOKEN to apply to GitHub

File overview

File Description
labels.json Single source of truth for all label definitions
generate_label_docs.py Generates LABELS.md with shields.io badge previews from labels.json
sync_labels.py Syncs labels to GitHub repositories via the REST API
LABELS.md Generated label documentation (do not edit manually)
requirements.txt Python dependencies (requests)