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:
- On release tag push, build docs from that tag and deploy to a versioned path (e.g.,
/v0.8.12/)
- On merge to
main, build and deploy to /latest/
- Add a version dropdown to the site header
- 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.
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 tomainbut before a new release was cut. The--hostoption 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 tomain(current behavior, unchanged)vX.Y.Z-- built and deployed on each GitHub release, matching the published binaryThe 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:
/v0.8.12/)main, build and deploy to/latest/Alternatives considered
latest: Add a notice like "You are viewing unreleased documentation" -- simpler but doesn't fully solve the problem since users land onlatestfrom search engines.