Problem Statement
OpenShell docs are currently published through Fern with a single latest version. That makes older release behavior hard to inspect after breaking changes land, because users following an older installed OpenShell version only see the newest docs at docs.nvidia.com/openshell/latest/....
This mattered during the v0.0.37 gateway lifecycle break: users needed docs that matched v0.0.36 behavior while the current docs described the new package-managed gateway model.
Proposed Design
Publish Fern documentation as versioned docs for each tagged OpenShell release.
Expected user-facing behavior:
https://docs.nvidia.com/openshell/latest/... continues to point at the current release or current published default.
- Each release gets a stable Fern docs version, for example
https://docs.nvidia.com/openshell/v0.0.37/....
- The Fern version selector lists
Latest plus recent tagged releases.
- Release notes and installation pages can link directly to the docs version that matches the release being described.
Implementation shape:
- Extend
fern/docs.yml beyond the current single Latest entry under versions: so release-specific slugs can be published.
- Update
.github/workflows/release-tag.yml publish-fern-docs to publish a release-specific docs version when a tag is released, using the release tag as the Fern slug/display name.
- Preserve existing
/openshell/latest/... redirects and canonical links.
- Decide whether version entries are generated during release publish or maintained through a committed versions manifest that Fern consumes.
- Add a small docs/publish note explaining how a release docs version is created and how to preview it.
Alternatives Considered
- Keep only
latest and rely on GitHub release notes for historical behavior. This is too thin for breaking changes because users need full installation, CLI, and Kubernetes docs for their installed version.
- Link users to raw docs in GitHub tags. That preserves history but loses the Fern navigation, search, styling, and version selector.
- Maintain separate static docs sites per release manually. This would work, but it creates avoidable release overhead and drift; Fern's versioning support should own this.
Agent Investigation
- Loaded the
create-github-issue skill and followed the feature request template.
- Checked for duplicates with
gh issue list --repo NVIDIA/OpenShell --search "fern docs versioned release documentation" --state all --limit 20; no matching issues were returned.
- Inspected
fern/docs.yml; it currently has only:
display-name: Latest
path: ../docs/index.yml
slug: latest
- Inspected
.github/workflows/release-tag.yml; the publish-fern-docs job checks out the release tag and runs fern generate --docs, but does not create or publish a release-specific Fern version.
Problem Statement
OpenShell docs are currently published through Fern with a single
latestversion. That makes older release behavior hard to inspect after breaking changes land, because users following an older installed OpenShell version only see the newest docs atdocs.nvidia.com/openshell/latest/....This mattered during the v0.0.37 gateway lifecycle break: users needed docs that matched v0.0.36 behavior while the current docs described the new package-managed gateway model.
Proposed Design
Publish Fern documentation as versioned docs for each tagged OpenShell release.
Expected user-facing behavior:
https://docs.nvidia.com/openshell/latest/...continues to point at the current release or current published default.https://docs.nvidia.com/openshell/v0.0.37/....Latestplus recent tagged releases.Implementation shape:
fern/docs.ymlbeyond the current singleLatestentry underversions:so release-specific slugs can be published..github/workflows/release-tag.ymlpublish-fern-docsto publish a release-specific docs version when a tag is released, using the release tag as the Fern slug/display name./openshell/latest/...redirects and canonical links.Alternatives Considered
latestand rely on GitHub release notes for historical behavior. This is too thin for breaking changes because users need full installation, CLI, and Kubernetes docs for their installed version.Agent Investigation
create-github-issueskill and followed the feature request template.gh issue list --repo NVIDIA/OpenShell --search "fern docs versioned release documentation" --state all --limit 20; no matching issues were returned.fern/docs.yml; it currently has only:display-name: Latestpath: ../docs/index.ymlslug: latest.github/workflows/release-tag.yml; thepublish-fern-docsjob checks out the release tag and runsfern generate --docs, but does not create or publish a release-specific Fern version.