Skip to content

fix(fern): pin frozen version content via git archive at publish time#316

Merged
dmitsh merged 2 commits into
NVIDIA:mainfrom
pdmack:fix/fern-version-content-pinning
May 8, 2026
Merged

fix(fern): pin frozen version content via git archive at publish time#316
dmitsh merged 2 commits into
NVIDIA:mainfrom
pdmack:fix/fern-version-content-pinning

Conversation

@pdmack

@pdmack pdmack commented May 8, 2026

Copy link
Copy Markdown
Contributor

Description

Frozen version entries in fern/docs.yml pointed at ../../docs/ — the live docs directory — so both "Latest" and "v0.3.0" served identical current content.

Adopts the git archive pattern from NVIDIA/NVSentinel#1263:

  • fern/versions/v0.3.0.yml: paths changed from ../../docs/ to v0.3.0-content/ (populated at CI time)
  • publish-fern-docs.yml: fetch-tags: true on checkout, new step loops over fern/versions/v*.yml and runs git archive to extract docs from each tag into fern/versions/vX.Y.Z-content/
  • fern/versions/.gitignore: excludes *-content/ directories from the repo

Fixes #315

Checklist

  • I am familiar with the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.
  • All commits are signed off per DCO (git commit -s).

@pdmack pdmack requested a review from dmitsh as a code owner May 8, 2026 15:07
@copy-pr-bot

copy-pr-bot Bot commented May 8, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@greptile-apps

greptile-apps Bot commented May 8, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR fixes frozen documentation versions that were incorrectly serving live content by adopting a git archive pattern to extract version-pinned docs at publish time. The root cause was that fern/versions/v0.3.0.yml paths pointed at ../../docs/ (the live directory), making every version show the same current content.

  • publish-fern-docs.yml: Adds fetch-tags: true to checkout and a new step that loops over fern/versions/v*.yml files, resolves each as a git tag, and uses git archive | tar to extract the tag's docs/ tree into a fern/versions/${version}-content/ staging directory. set -eo pipefail ensures any archive failure surfaces immediately.
  • fern/versions/v0.3.0.yml: All 15 page paths updated from ../../docs/ to v0.3.0-content/, which resolves (relative to the yml file in fern/versions/) to the correct staging directory created by the CI step.
  • fern/versions/.gitignore: New file with *-content/ so generated staging directories are never accidentally committed.

Confidence Score: 5/5

Safe to merge — the change is self-contained, the archive extraction is guarded by set -eo pipefail, and a missing tag emits a warning rather than silently publishing stale content.

All three files make consistent, targeted changes: the workflow correctly uses fetch-tags to bring tag objects into scope for git archive, strip-components=1 produces exactly the directory layout expected by the updated yml paths, and the gitignore prevents generated directories from leaking into the repo. No logic errors or unsafe failure modes were found.

No files require special attention.

Important Files Changed

Filename Overview
.github/workflows/publish-fern-docs.yml Adds fetch-tags and a git-archive loop to populate frozen-version content directories; uses set -eo pipefail for safe error handling.
fern/versions/v0.3.0.yml All 15 doc paths updated from live ../../docs/ to the version-pinned v0.3.0-content/ staging directory; paths are correctly relative to the yml file's own location.
fern/versions/.gitignore New gitignore that excludes all *-content/ directories, preventing generated content from being accidentally committed.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant Git as git (local)
    participant Fern as fern CLI

    GH->>Git: checkout (fetch-tags: true)
    Note over Git: Tag refs + objects for all v* tags available

    loop "for each fern/versions/v*.yml"
        GH->>Git: git rev-parse v0.3.0
        Git-->>GH: tag exists ✓
        GH->>Git: git archive v0.3.0 -- docs/
        Git-->>GH: "tar stream (docs/*)"
        GH->>GH: "tar -x --strip-components=1 -C fern/versions/v0.3.0-content/"
        Note over GH: fern/versions/v0.3.0-content/overview.md, api.md, …
    end

    GH->>Fern: fern generate --docs
    Fern->>GH: reads fern/versions/v0.3.0.yml
    Note over Fern: path: v0.3.0-content/overview.md → fern/versions/v0.3.0-content/overview.md
    Fern-->>GH: publishes pinned v0.3.0 content ✓
Loading

Reviews (2): Last reviewed commit: "fix(ci): add pipefail to frozen version ..." | Re-trigger Greptile

Comment on lines +48 to +50
- name: Checkout frozen version content
run: |
for version_file in fern/versions/v*.yml; do

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Without set -eo pipefail, a failure in git archive (e.g., docs/ path absent in a future tag, shallow-clone object miss) or in tar is silently swallowed. The step prints "Extracted docs from $version" regardless, and fern generate then fails later with a confusing "file not found" rather than a clear archive error.

Suggested change
- name: Checkout frozen version content
run: |
for version_file in fern/versions/v*.yml; do
- name: Checkout frozen version content
run: |
set -eo pipefail
for version_file in fern/versions/v*.yml; do

@pdmack pdmack force-pushed the fix/fern-version-content-pinning branch from 386afa0 to fedd606 Compare May 8, 2026 15:12
Frozen versions pointed at ../../docs/ (the live docs directory),
serving current content for all versions. Switch to the git archive
pattern used by NVSentinel: at publish time, extract docs from each
version's git tag into fern/versions/vX.Y.Z-content/ directories.

- v0.3.0.yml paths now reference v0.3.0-content/ (populated at CI time)
- Publish workflow: fetch-tags + git archive step extracts docs per tag
- .gitignore excludes *-content/ dirs from the repo

Signed-off-by: Pete MacKinnon <[email protected]>
@pdmack pdmack force-pushed the fix/fern-version-content-pinning branch from fedd606 to da6bd01 Compare May 8, 2026 15:16
A failed git archive or tar would silently produce an empty content
directory. Add set -eo pipefail so the step fails immediately.

Signed-off-by: Pete MacKinnon <[email protected]>
@dmitsh dmitsh merged commit c3cc538 into NVIDIA:main May 8, 2026
4 checks passed
@pdmack pdmack deleted the fix/fern-version-content-pinning branch May 8, 2026 18:48
dmitsh pushed a commit that referenced this pull request May 14, 2026
… fern errors (#322)

The preview build workflow did not run git archive to populate
fern/versions/v0.3.0-content/, causing fern generate --preview to fail
with ENOENT on every PR since #316 merged. Add the same git archive
step from the publish workflow.

Also switch the comment workflow's Generate preview URL step from the
OUTPUT=$(fern ... 2>&1) pattern to tee-based streaming so fern errors
are visible in the Actions log on failure.

Fixes #321

Signed-off-by: Pete MacKinnon <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(fern): frozen doc versions serve current content instead of tagged content

2 participants