Skip to content
Muoto Docs

Release and versioning policy

This policy defines how the documentation project is versioned and released. It is deliberately lightweight: Muoto has no public release lines yet, so this page documents the semantics that will apply before the first public release and the explicit trigger for heavier machinery.

Latest, current, stable

Section titled “Latest, current, stable”
  • Latest — the docs describe the current development state of the main branch. Until the first public release, the site serves latest, and every page is required to describe the shipped product: unsupported or unreleased functionality is visibly marked (see the getting-started tutorial status marks).
  • Stable — the docs for the current public release line. Once the first public release exists, the site’s default target becomes stable, and unreleased changes are marked as previews rather than documented as available.
  • Current — whichever target the site serves by default. Today that is latest; after the first public release it is stable. A banner on the site states the target.

The transition to a stable channel happens at the first public release, not before.

SDK reference attribution

Section titled “SDK reference attribution”

The generated SDK reference is stamped with the SDK version it describes (APPHOST_PROTOCOL_VERSION, currently SDK v1) and the exact source revision it was generated from. Every page carries both in its metadata, so a reader can always tell which code a signature came from.

Released packages remain attributable to SDK versions through their sdkCompatibility metadata (see Package authoring). The package catalog surfaces that compatibility on each package page.

Historical reference remains reachable in two ways:

  1. The reference is generated from a source revision — checking out a release tag and running npm run generate:reference reproduces that release’s reference exactly.
  2. Once release lines exist, each release tag is accompanied by a docs snapshot that is kept in the repository rather than deleted.
Section titled “Historical links and retention”
  • Pages are never deleted silently. A removed or superseded page either becomes a redirect to its replacement or is marked archived with a link to what replaced it.
  • Cross-repository links use stable repository paths (see Source of truth), so links into docs/, sdk/, and packages/ keep working across releases.
  • The git history of this docs project is the ultimate retention layer: every state of every page is recoverable from the repository.

Trigger for full-site versioning

Section titled “Trigger for full-site versioning”

Heavier versioning machinery (per-major-version roots such as /v1/, /v2/, parallel sidebar trees, or separate static deployments per version) is adopted only when two or more supported public release lines must be readable simultaneously — for example when breaking SDK changes require documenting both generations and users of the older generation still need correct docs.

Until that trigger fires, the project avoids version-copy machinery: one site, one target, clear status marks, and generated reference attributable to the exact source revision.

See also

Section titled “See also”