Skip to content

DR-002: Use Semantic Versioning 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

Semantic Versioning (SemVer) with Trunk-Based Development.

Format: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes
  • MINOR: New features (backward-compatible)
  • PATCH: Bug fixes

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

Git Tags: <module>-v<version> (e.g., cli-v2.0.1)

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

Negative: Requires discipline, feature flags needed, version tracking overhead, strict conventions

Alternatives Considered

  1. Git Flow: Rejected - too slow, unified versioning doesn't fit module independence
  2. CalVer: Rejected - doesn't communicate compatibility
  3. 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.