Skip to content

[FEATURE] Support versioned documentation site #646

@sergio-sisternes-epam

Description

@sergio-sisternes-epam

Problem

The documentation site is deployed on every merge to main, but users install APM from published releases. This creates a window where the docs reference features that don't yet exist in the latest release binary, leading to confusion and bug reports.

Real example: #641 -- a user on v0.8.11 followed the docs for apm marketplace add --host, which was documented after PR #589 merged to main but before a new release was cut. The --host option didn't exist in their installed version, so they filed a bug.

Proposed solution

Support multiple documentation versions:

  • latest -- built and deployed on every merge to main (current behavior, unchanged)
  • vX.Y.Z -- built and deployed on each GitHub release, matching the published binary

The default landing page should point to the latest stable release version, with a version switcher allowing users to navigate to latest (for contributors/pre-release) or any prior release.

Suggested approach

Starlight (the current doc framework) supports this via plugins or build-time configuration. The general pattern is:

  1. On release tag push, build docs from that tag and deploy to a versioned path (e.g., /v0.8.12/)
  2. On merge to main, build and deploy to /latest/
  3. Add a version dropdown to the site header
  4. Default root URL redirects to the latest stable release

Alternatives considered

  • Banner warning on latest: Add a notice like "You are viewing unreleased documentation" -- simpler but doesn't fully solve the problem since users land on latest from search engines.
  • Only deploy docs on release: Would eliminate the mismatch but delays documentation for contributors and reviewers.

Metadata

Metadata

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions