Versioning and Release Management¶
Document and specification versioning¶
Documents and specifications in this repository use a semver-like major.minor.patch version in
their front matter (see document-metadata-standard.md).
- major — a breaking change or a redefinition of the document's meaning: a policy rule reversed, a specification's contract changed in an incompatible way, a standard replaced with a substantially different approach.
- minor — a material addition that does not break existing meaning: a new section, a new requirement added without removing or contradicting existing ones, a new optional field in a specification.
- patch — a clarification, correction, typo fix, or formatting change that does not alter the document's meaning.
New documents start at 0.1.0 while in draft/proposed status. Reaching 1.0.0 is a
reasonable (but not required) signal that a document has reached its first approved state; this
is a convention, not a rule enforced by tooling.
Every version bump to an approved document should be traceable to a reason — either an entry in
that document's own change history/commit log, or (for company-wide-significant changes) an ADR.
Product releases¶
This document defines the versioning convention; it does not itself define how a venture records a shipped release. That lives at the venture level, conceptually:
- Each venture's product roadmap (venture-level, not duplicated here) tracks planned and shipped work.
- Release records (see documentation-taxonomy.md — a
recordtype document) capture what actually shipped, when, and any migration implications, for a given product release. - A reusable release-record template is expected under
work/templates/(see docs/ai/planning-and-work-logs.md) — this document links forward to that convention rather than defining the template itself, since templates live with the work-management tooling, not with company governance policy. - Company-level CHANGELOG.md tracks changes to this repository itself (its governance, tooling, and structure), not venture product releases.
Relationship to Git history¶
Git commit history is the underlying source of truth for exactly what changed and when (see git-and-notion-responsibilities.md). Version numbers and release records are a human-readable summary layered on top of that history, not a replacement for it.