Skip to content

DR-011: CalVer for Documentation, SemVer for Code

Home › Reference › Decision Records › Dr011

Status

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

Date: 2024-12-05

Context

Different artifact types have different upgrade semantics. Code artifacts need API compatibility signals. Documentation releases are time-based.

Problem: How to communicate appropriate version semantics for different module types?

Decision

Mixed versioning strategy based on artifact type and release semantics.

Versioning Schemes:

  1. SemVer (API compatibility):
  2. Modules: r2r-cli, ext-eac, eac-commands, eac-mcp-commands, implicit-r2r-cli, r2r-installer, vscode-ext-commit
  3. Format: MAJOR.MINOR.PATCH
  4. Breaking changes → MAJOR bump

  5. Communicates upgrade safety

  6. CalVer (time-based releases):

  7. Modules: docs, books, release-docs, r2r-eac-bundle
  8. Format: YYYY.MM or YYYY.0M
  9. Independent documentation updates

  10. No API compatibility concerns

  11. Implicit (library versioning):

  12. Modules: eac-core, eac-specs
  13. Versioned via dependent modules
  14. No independent releases

  15. Reduces version noise

  16. No Versioning (infrastructure):

  17. Modules: repository, templates, github, container base images
  18. Not independently released
  19. Development utilities

Release Bundles:

  • CalVer-versioned aggregates
  • Combine multiple module versions
  • Format: r2r-(r2r_version) ∞ eac-(eac_version)
  • Example: r2r-(0.0.24) ∞ eac-(0.0.15)

Consequences

Positive: Clear semantics, independent cadences, appropriate signaling, flexible releases, reduced version noise

Negative: Mixed schemes complexity, version mapping overhead, documentation needed

Alternatives Considered

  1. SemVer Only: Rejected - poor semantics for time-based documentation, forces unnecessary major bumps
  2. CalVer Only: Rejected - no API compatibility signals, upgrade uncertainty for code
  3. Single Unified Version: Rejected - forces coupled releases, limits flexibility

Tutorials | How-to Guides | Explanation | Reference

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