Release and versioning policy

Platform spec feature

Release and versioning policy

Back to Spec maintenance ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-git-version-axis Git is the canonical specification version axis Accepted

   Contract truth is the platform-spec tree at a commit; no parallel normative URL version hierarchy.

   Context

   Version-segmented doc sites diverged from the implementation on main. Inception record D-INC-0007 states the platform-wide choice.

   Decision

   The platform specification under /platform-spec/ is versioned by Git (typically main). Readers and tooling must treat the spec at a given commit as the contract for that commit; there is no parallel normative URL hierarchy such as /platform-spec/v0.2/....

   Consequences

   Site deploy and release policy track main; lastReviewed records alignment dates.

   Verification anchors

   D-INC-0007.

   Open full ADR page

2. 0002-stable-urls Stable platform-spec URLs across releases Accepted

   Behavioral change edits normative text and metadata, not path version segments.

   Context

   Renaming or version-prefixing feature paths broke bookmarks and relatedTopics links across domains.

   Decision

   Feature and language-meta paths must remain stable across releases. Behavioral change is expressed by editing normative text and metadata (status, lastReviewed, embedded decisions), not by introducing version segments in site paths.

   Consequences

   Redirects handle legacy Starlight paths; normative slugs under platform-spec/ stay fixed.

   Verification anchors

   site/website Astro routes; platform-spec nav tree generation.

   Open full ADR page

3. 0003-v0x-delivery-bands v0.x bands label delivery scope not doc editions Accepted

   Roadmap bands scope implementation targets; they do not fork normative URLs.

   Context

   Readers interpreted v0.2 labels as alternate authoritative spec trees at the same URL.

   Decision

   Labels such as v0.1, v0.2, or roadmap bands describe what the reference platform targets shipping, not separate specification editions. A page may mention a band when scoping work; it must not imply an older band remains authoritative at the same URL without explicit Superseded decision notes.

   Consequences

   status: Proposed plus band mentions are expectations; status: Standard plus bands scope verification targets.

   Verification anchors

   Feature hub maturity tables; embedded Superseded ADR links.

   Open full ADR page

4. 0004-single-normative-tree Single normative platform-spec tree Accepted

   Only /platform-spec/ is normative; legacy execution/corelib/book paths are non-normative unless bridged.

   Context

   Parallel non-normative legacy trees (/execution/, /corelib/, Starlight guides) were cited as law alongside platform-spec.

   Decision

   The Platform specification domain is the one normative documentation tree for language and platform contracts. Legacy trees are non-normative only: informative /execution/ and /corelib/ Starlight paths, plus book and guides, unless explicitly bridged per Non-normative bridge docs policy.

   Consequences

   Public site exposes Platform specification and Book only; bridge pages link canonical destinations.

   Verification anchors

   Legacy spec mapping; PSC005 stale legacy bridge checks.

   Open full ADR page

Articles

• No directly attached article pages for this node.

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 5 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	no	no
implementation-anchors	no	no

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Spec maintenance

  Parent area

• Feature
  Specification authority and embedded decisions

  Maturity and authority model

• Feature
  Last reviewed policy

  Review freshness on high-churn pages

Normative platform contract

1. Canonical version axis — The platform specification under /platform-spec/ is versioned by Git (typically main as the rolling integration branch). Readers and tooling must treat the spec at a given commit as the contract for that commit; there is no parallel normative URL hierarchy such as /platform-spec/v0.2/....
2. Stable URLs — Feature and language-meta paths must remain stable across releases. Behavioral change is expressed by editing normative text and metadata (status, lastReviewed, embedded decisions), not by introducing version segments in site paths.
3. v0.x bands are delivery scope, not doc versions — Labels such as v0.1, v0.2, or roadmap bands describe what the reference platform targets shipping, not separate specification editions. A page may mention a band in prose when scoping implementation work; it must not imply that an older band remains authoritative at the same URL without explicit Superseded decision notes.
4. Single normative entry — The Platform specification domain is the one normative documentation tree for language and platform contracts. Legacy trees (/execution/, /corelib/, informative book and guides) are non-normative unless explicitly bridged per Non-normative bridge docs policy.

How bands interact with maturity

Label	Role in documentation
Git revision / lastReviewed	When the normative text was last aligned with implementation
status: Proposed	Contract still forming; band mentions are expectations, not guarantees
status: Standard	Enforceable at the current Git revision; band mentions scope verification targets
Embedded Superseded decisions	Historical choice retired at a noted revision; replacement section owns current law

Tooling and release artifacts

• CLI and package publication may use rolling tags (for example cli-latest) for binaries; that does not fork the spec URL space.
• Registry-assigned package versions and lockfiles are tooling/execution concerns; their normative definitions live under platform-spec features with relatedTopics links, not under version-prefixed doc paths.

Maintainer expectations

When a delivery band closes a gap (for example promoting fibers from Proposed to Standard), update normative prose, verification anchors, and lastReviewed in the same change set as the implementation merge when possible. Do not leave Standard pages describing behavior that only exists on another branch without a Proposed downgrade or an explicit decision noting the gap.

Decisions

No open decisions. Closed maintenance ADRs under adr/ — D-COMM-VERS-0001 through D-COMM-VERS-0004 (reader ADRs tab). Inception cross-cut: D-INC-0007.