Protobuf Development Workflow

Goal

Manage the local and CI development lifecycle for Protocol Buffers within the Liverty Music project.

Instructions

1. •

   Environment Setup:

   • •Manager: mise manages all tools.
   • •Install: Run mise install in root.
   • •Hooks: Run pre-commit install.
2. •

   Local Development Loop:

   • •Lint: buf lint
   • •Format: buf format -w
   • •Breaking Change: buf breaking --against '.git#branch=main'
3. •

   Pre-commit Hooks:

   • •Commit: buf lint, buf format, breaking change detection, prettier.
   • •Push: Schemas pushed to BSR for remote code generation.
4. •

   CI/CD Pipeline:

   • •PR Workflow (.github/workflows/buf-pr-checks.yml):
     • •Runs on all PR events including label changes.
     • •Validates: lint, format (--diff --exit-code), breaking changes, dry-run generation.
     • •Skip Breaking Changes: Add buf skip breaking label to PR to bypass breaking change detection.
       • •Used for intentional breaking changes (e.g., security fixes, MVP iterations).
       • •Label must exist in repository (create with gh label create "buf skip breaking").
       • •Workflow automatically responds to labeled/unlabeled events.
       • •Reference: https://buf.build/docs/bsr/ci-cd/github-actions/#skip-breaking-change-detection-using-labels
   • •Release Workflow (.github/workflows/buf-release.yml):
     • •Triggers on GitHub releases.
     • •Automatic buf push with release tag as BSR label.
     • •Requires BUF_TOKEN secret.

Constraints

• •Do NOT bypass pre-commit hooks.
• •Do NOT use global buf installation; use mise version.
• •Do NOT run buf generate EVER. Local generation is strictly forbidden to ensure consistency with BSR.

Example

# Workflow for a new change
mise install
buf lint && buf format -w
buf breaking --against '.git#branch=main'
git add .
git commit -m "feat: updates"