Skip to content

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

Closed
Closed
feat(docs): publish versioned Fern docs for releases#1296
Assignees
pimlock
Labels
area:buildRelated to CI/CD and buildsarea:docsDocumentation and examplesstate:acceptedA maintainer decided OpenShell should pursue this issuestate:in-progressWork is currently in progress

Description

@drew
drew
opened on May 9, 2026

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.

Activity

  1. drew
    added
    area:docsDocumentation and examples
    area:buildRelated to CI/CD and builds
    on May 9, 2026
  2. pimlock
    self-assigned this
    on May 25, 2026
  3. pimlock
    added
    state:in-progressWork is currently in progress
    on May 25, 2026

  4. pimlock commented on May 26, 2026

    @pimlock
    pimlock
    on May 26, 2026
    Collaborator

    I propose we use a CI-managed docs-website branch, similar to Dynamo (with some others new pages following this pattern as well).

    High-level model:

    • main remains the source of truth for authored docs in docs/ and Fern config in fern/.
    • docs-website stores the generated Fern publish layout and frozen version snapshots.
    • latest is a stable URL alias for one concrete release snapshot, not its own mutable docs copy.
    • dev tracks docs from main, aligned with the dev release stream.
    • Historical versions can be added manually by workflow dispatch.
    • PR previews stay unchanged: they preview only the PR's docs as a single available version.

    For example, after publishing the current release and one historical version, the generated branch would contain:

    fern/
├── docs.yml
├── versions/
│   ├── dev.yml
│   ├── v0.0.48.yml
│   └── v0.0.36.yml
├── pages-dev/
├── pages-v0.0.48/
└── pages-v0.0.36/

    The published URLs would behave like:

    • /openshell/latest/... -> same content as /openshell/v0.0.48/...
    • /openshell/dev/... -> current docs from main
    • /openshell/v0.0.36/... -> frozen historical docs from before the gateway lifecycle refactor

    Alternatives considered, roughly best to worst:

    1. Separate docs repository.
      This gives the cleanest separation between source code and accumulated docs snapshots, but code and docs changes would land in separate repos, release automation would need cross-repo credentials, and it would be harder to keep a release tag, docs snapshot, and publish status atomic.

    2. Publish all versions from main.
      This keeps automation simple, but every old docs snapshot would live on main, bloating the branch, adding irrelevant search/grep hits, and increasing the chance that normal docs edits accidentally touch frozen versions.

    3. Regenerate historical versions from tags on every publish.
      This avoids storing generated snapshots, but publishes become slower and less deterministic. Old tags may fail under newer tooling or Fern config, and it becomes harder to curate exactly which old versions we keep.

    4. Link users to docs in GitHub tags.
      This preserves history with no new automation, but users lose Fern navigation, search, styling, redirects, version selector, and canonical docs URLs.

    5. Publish a separate static docs site per release.
      This isolates versions, but creates the most operational overhead, increases config drift, and makes navigation between versions worse than Fern's built-in version selector.

    Recommended next step if this direction sounds right:

    Run a spike that creates the docs-website branch and proves the branch layout with three versions:

    • dev from main
    • latest pointing at v0.0.48
    • v0.0.36 as a historical snapshot from before the gateway lifecycle refactor

    The spike should validate that Fern accepts the generated layout, that /latest, /dev, and /v0.0.36 resolve correctly, and that PR previews remain unchanged.

    References:

  5. moezdil commented on May 26, 2026

    @moezdil
    moezdil
    on May 26, 2026
    Contributor

    thx for the detailed writeup @pimlock,
    the docs-website branch model makes sense.

    a few things i want to make sure we have covered before the spike:

    nr1) url behavior for latest: fern docs say the first version in the list gets unversioned paths (e.g. /getting-started not /latest/getting-started). how do we preserve the existing /openshell/latest/... URLs?

    nr2) fern plan limits: fern caps versions at 3 (hobby), 10 (team), or unlimited (enterprise). worth confirming which plan we're on before deciding how many versions to keep.

    nr3) ci workflow: the branch layout is clear but the automation is not. when a release tag is pushed, what updates docs-website? and does dev update on every merge to main?

    nr4) snapshot drift: frozen version files in docs-website may break over time if the fern cli or config changes. is there a plan for that?

  6. pimlock commented on Jun 5, 2026

    @pimlock
    pimlock
    on Jun 5, 2026
    Collaborator

    Replying to @mesutoezdil's checklist in #1296 (comment):

    Thanks, these are exactly the right failure modes to cover. Here is how I think the spike/first automation pass should handle each one:

    1. latest URL behavior: keep latest as an explicit generated version/alias in docs-website, and keep redirects for /openshell/latest/.... In the first pass, latest is a moving release alias, not a dedicated historical version route like /openshell/v0.0.57/....

    2. Fern plan limits: confirmed we are good.

    3. CI workflow: add a dedicated sync-docs workflow that updates one docs snapshot from a source ref. Manual first; later release-dev can dispatch dev with the built commit SHA, and release-tag can dispatch latest with the release tag/SHA.

    4. Snapshot drift: store snapshots intentionally on docs-website so old versions are not regenerated unless explicitly requested. Every sync/publish path should run Fern validation before publishing, and historical versions should only be touched when the workflow is asked to sync that slug.

  7. pimlock commented on Jun 5, 2026

    @pimlock
    pimlock
    on Jun 5, 2026
    Collaborator

    Docs website automation follow-up

    Proposed first automation pass:

    • Keep docs-website as the generated-only branch containing Fern config, shared assets/components, and frozen pages-{slug} snapshots.
    • Add sync-docs.yml, manual first, with inputs for channel, source_ref, optional version_slug, and optional display_name.
    • sync-docs.yml checks out the requested source ref, checks out docs-website, copies only the requested docs snapshot into fern/pages-{slug}/, regenerates fern/versions/{slug}.yml, updates the version entry in fern/docs.yml, validates, and commits only when there is a diff.
    • Add workflow concurrency on the docs branch mutation path: concurrency.group: docs-website, cancel-in-progress: false, so only one sync/publish operation mutates or publishes at a time.
    • Add publish-docs-website.yml, also manual first. It checks out docs-website, runs fern check, and defaults to a Fern preview. Production publish requires explicitly selecting production mode.
    • Keep PR previews unchanged for now; they continue to preview the PR source branch as a single-version docs site.

    Once the manual path proves stable, the next step is wiring release automation:

    • release-dev dispatches sync-docs.yml with channel=dev and the commit SHA that was built.
    • release-tag dispatches sync-docs.yml with channel=latest and the release tag/SHA.
    • Production publish can stay manual until we are comfortable promoting sync+publish into the release workflows.

  8. github-actions commented on Aug 30, 2026

    @github-actions
    github-actionsBot
    on Aug 30, 2026 – with GitHub Actions

    This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.

  9. github-actions
    added
    state:staleInactive item at risk of automatic closure.
    on Aug 30, 2026
  10. pimlock
    added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    and removed
    state:staleInactive item at risk of automatic closure.
    on Sep 2, 2026
  11. johntmyers
    closed this as completedon Sep 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:buildRelated to CI/CD and buildsarea:docsDocumentation and examplesstate:acceptedA maintainer decided OpenShell should pursue this issuestate:in-progressWork is currently in progress

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions