1 ADR 0019 semantic versioning and v1 release
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0019: Semantic Versioning and v1 Release

Status: superseded Superseded by: 0041

Context

The accepted v1 baseline is now complete. Memories needs an explicit release versioning policy so self-hosters can reason about deployed images, export compatibility metadata, bugfix upgrades, and future migration expectations.

Before v1 closure, code and container examples used development versions such as 0.1.0-dev. That was useful while the baseline was still moving, but it is not clear enough for long-lived archives, backup/restore evidence, or operator support.

Decision

Memories uses Semantic Versioning from the v1 baseline onward.

  • The first completed baseline release is 1.0.0.
  • Runtime application metadata, Docker image tags, package metadata, API contract metadata, and export sourceAppVersion should use the same release version.
  • Patch versions are for backward-compatible bug fixes and hardening that do not require operator-visible migration decisions.
  • Minor versions are for backward-compatible features or UX improvements that preserve v1 data ownership, backup/restore, authorization, and worker boundary semantics.
  • Major versions are for intentional breaking changes to public API contracts, persisted data/restore compatibility, ownership/sharing semantics, or operator migration requirements.
  • Pre-release identifiers may be used for future unstable work, e.g. 1.1.0-alpha.1 or 2.0.0-rc.1, but shipped v1 baseline artifacts should not retain -dev versions.

Consequences

  • MEMORIES_APP_VERSION becomes a meaningful operator/release value and defaults to 1.0.0 in example configuration and local fallback metadata.
  • Inspectable exports created from v1.0.0 should identify sourceAppVersion as 1.0.0 while keeping export format versioning separate from app release versioning.
  • Future specs/ADRs should call out whether a change is patch/minor/major and why, especially when migrations or restore compatibility are involved.
  • The strict browser TXT unsupported-file hardening deferred at v1 closure is a candidate patch-level hardening item unless its eventual fix changes public API semantics.

Revisit triggers

  • Introducing a supported restore-from-export path.
  • Changing the fidelity backup unit or migration compatibility guarantee.
  • Publishing multiple independently-versioned clients/workers with compatibility matrices.
  • Introducing public APIs or plugin contracts that need their own versioning policy.