Skip to content

adr-007-stack-versioning.md

Latest commit

 

History

History
36 lines (28 loc) · 1.55 KB

adr-007-stack-versioning.md

File metadata and controls

36 lines (28 loc) · 1.55 KB
Raw

ADR-007: The stack itself is versioned (SemVer + Keep a Changelog)

  • Status: accepted
  • Date: 2026-08-06
  • Related: every ADR — this is the meta-decision that makes the others durable

Context

The stack grew organically: skills, scripts and templates changed in the owner's vault for months before being extracted into a reusable project. There was exactly one git commit and no version, so nobody (including the owner) could answer "what changed since I installed this?" or roll back a bad upgrade. The system that manages knowledge had no memory of its own changes.

Decision

brainstack is versioned like the software it is:

  • Semantic Versioning (MAJOR.MINOR.PATCH) with the current version in VERSION and git tags (v1.0.0).
  • Keep a Changelog in CHANGELOG.md — every user-facing change gets an entry with what/when/why.
  • Architecture Decision Records in docs/adr/ for every decision with alternatives considered — the why survives the people who made it.
  • The release procedure is documented in docs/RELEASING.md and executed as a checklist (bump → changelog → tag → verify → publish).

Consequences

  • git checkout vX.Y.Z reproduces a coherent stack; upgrades are reviewable diffs, not folklore.
  • A deployment that lags behind can see exactly what it is missing.
  • New maintainers (or the owner, six months later) can reconstruct the reasoning behind every structural choice from the ADRs.
  • Versioning the stack costs minutes per release and removes an entire class of "what changed?" confusion.