Skip to content

DR-002: Use Mixed Versioning Strategy with Trunk-Based Development

Home › Reference › Decision Records › Dr002

Status

  • [x] Accepted
  • [ ] Proposed
  • [ ] Rejected
  • [ ] Deprecated
  • [ ] Superseded

Date: 2025-11-03

Context

Mono-repository needs versioning for independent modules, coordinated branching, and traceability.

Problem: How to version modules and manage branches for rapid development with stability?

Decision

Mixed versioning strategy with Trunk-Based Development.

Versioning Schemes:

  • SemVer (code artifacts with API contracts): r2r-cli, ext-eac, eac-commands, eac-mcp-commands, implicit-r2r-cli, r2r-installer, vscode-ext-commit
  • Format: MAJOR.MINOR.PATCH (e.g., 0.0.24)

  • MAJOR: Breaking changes, MINOR: New features, PATCH: Bug fixes

  • CalVer (documentation and aggregate bundles): docs, books, release-docs, r2r-eac-bundle

  • Format: YYYY.MM or YYYY.0M (e.g., 2025.12)

  • Time-based releases, independent from code changes

  • Implicit (internal libraries): eac-core, eac-specs

  • No independent releases, versioned via dependent modules

Release Bundles: CalVer-versioned aggregates combining multiple module versions (e.g., r2r-(r2r_version) ∞ eac-(eac_version))

Commit Format: <module>: <type>: <description> (e.g., cli: feat: add command)

Git Tags: <module>-v<version> (e.g., r2r-cli-v0.0.24, docs-v2025.12)

Branching:

  • main always releasable
  • Short-lived branches (< 2 days)
  • Feature flags for incomplete work
  • Release tags on main

Version Bumps:

  • feat: → MINOR
  • fix: → PATCH
  • feat!: or BREAKING CHANGE: → MAJOR

Consequences

Positive: Clear upgrade semantics, fast integration, simple branching, continuous deployment, module independence, traceability, flexible versioning matches artifact semantics, documentation can evolve independently from code

Negative: Requires discipline, feature flags needed, version tracking overhead, strict conventions, mixed schemes complexity, version mapping overhead

Alternatives Considered

  1. Git Flow: Rejected - too slow, unified versioning doesn't fit module independence
  2. SemVer Only: Rejected - poor semantics for time-based documentation releases
  3. CalVer Only: Rejected - doesn't communicate API compatibility for code artifacts
  4. Manual Versioning: Rejected - error-prone, doesn't scale

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.