Skip to content

feat(docs): publish versioned Fern docs for releases #1296

@drew

Description

@drew

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:buildRelated to CI/CD and buildsarea:docsDocumentation and examples

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions