Versioning Strategy

Decision

Rolling current — a single "latest" version of the docs is always served. No per-release snapshots are cut at this stage.

Rationale

The documentation platform is new and the content is still evolving. Maintaining per-release snapshots requires a mature, stable content baseline and a defined snapshot cadence. Introducing snapshots prematurely would create divergence overhead before the content has reached that level of stability.

The rolling current model:

• Keeps all contributors focused on a single authoritative source of truth.
• Eliminates the need to backport fixes across multiple versioned copies.
• Reduces CI/CD complexity (no snapshot branches to build and host in parallel).
• Matches the current project phase where documentation tracks the main branch.

Upgrade Path to Per-Release Snapshots

When the project reaches a stable public API and release cadence, per-release versioning can be enabled using Docusaurus's built-in versioning support without refactoring existing content.

Prerequisites before switching

• At least one stable public release exists with docs worth preserving.
• A release manager is designated to own the snapshot workflow.
• CI pipelines are extended to build all active versioned snapshot directories.

How to cut the first snapshot

# From apps/docs directory
npx docusaurus docs:version 1.0.0
npx docusaurus docs:version --plugin-id user 1.0.0
npx docusaurus docs:version --plugin-id internal 1.0.0

Each command must be run separately because the site uses three independent plugin-content-docs instances (developer, user, internal). The first command versions the default (developer) plugin; the --plugin-id flag targets the other two. Skipping a command leaves that section unversioned and it will continue rolling.

This creates versioned snapshot directories for each section and adds entries to their respective versions.json files. Subsequent builds serve both the snapshots and the current rolling docs.

Resulting folder structure

apps/docs/
  developer/                          ← "next" (current / rolling)
  user/                               ← "next" (current / rolling)
  internal/                           ← "next" (current / rolling)
  versioned_docs/
    version-1.0.0/                    ← developer snapshot for v1.0.0
    version-1.1.0/                    ← developer snapshot for v1.1.0
  user_versioned_docs/
    version-1.0.0/                    ← user snapshot for v1.0.0
  internal_versioned_docs/
    version-1.0.0/                    ← internal snapshot for v1.0.0
  versions.json                       ← developer version list
  user_versions.json                  ← user version list
  internal_versions.json              ← internal version list
  versioned_sidebars/
    version-1.0.0-sidebars.json
  user_versioned_sidebars/
    version-1.0.0-sidebars.json
  internal_versioned_sidebars/
    version-1.0.0-sidebars.json

Snapshot cadence (when adopted)

Trigger	Action
Major release (N.0.0)	Always cut a snapshot
Minor release (N.M.0)	Cut a snapshot if public API changed
Patch release	No snapshot; rolling docs receive the fix
End of life for a version	Archive the snapshot (hide from the version switcher)

Search Compatibility

The local search plugin (@easyops-cn/docusaurus-search-local) indexes all versioned and rolling docs automatically. No additional configuration is required when adding snapshots.

Record

Date	Decision
2026-09-19	Adopted rolling current; per-release snapshot path documented