Skip to main content

Revision History Page + Release Strategy

Date: 2026-03-08 Status: Approved

Problem​

No visibility into what work is in progress or completed without running bd list locally. Need a persistent, browsable revision history in the docs site.

Design​

Revision History page (docs/revision-history.md)​

Two sections:

  1. Current Backlog — open beads issues grouped by functional area (control plane, data plane, infrastructure, frontend, docs/architecture), epics first then features/tasks in table format.

  2. Releases — completed work per release, newest first. An "Unreleased" section at the top captures closed issues not yet tagged in a GitHub release. When a release is cut, unreleased items move under the new version heading.

Release strategy​

  • Semantic versioning: 0.MINOR.PATCH while pre-1.0
  • 0.x.0 for feature batches or milestones
  • 0.x.y for bug fixes
  • GitHub releases via gh release create vX.Y.Z --generate-notes
  • First release: v0.1.0 covering all work to date

CLAUDE.md instruction​

After any bd create, bd close, or bd update --status, regenerate docs/revision-history.md:

  • Rebuild the backlog section from bd list --status open
  • Move newly closed issues to the "Unreleased" section
  • Group by functional area (plane)