fix(fern): pin frozen version content via git archive at publish time#316
Conversation
Greptile SummaryThis PR fixes frozen documentation versions that were incorrectly serving live content by adopting a
Confidence Score: 5/5Safe 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
Sequence DiagramsequenceDiagram
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 ✓
Reviews (2): Last reviewed commit: "fix(ci): add pipefail to frozen version ..." | Re-trigger Greptile |
| - name: Checkout frozen version content | ||
| run: | | ||
| for version_file in fern/versions/v*.yml; do |
There was a problem hiding this comment.
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.
| - 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 |
386afa0 to
fedd606
Compare
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]>
fedd606 to
da6bd01
Compare
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]>
… 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]>
Description
Frozen version entries in
fern/docs.ymlpointed at../../docs/— the live docs directory — so both "Latest" and "v0.3.0" served identical current content.Adopts the
git archivepattern from NVIDIA/NVSentinel#1263:fern/versions/v0.3.0.yml: paths changed from../../docs/tov0.3.0-content/(populated at CI time)publish-fern-docs.yml:fetch-tags: trueon checkout, new step loops overfern/versions/v*.ymland runsgit archiveto extract docs from each tag intofern/versions/vX.Y.Z-content/fern/versions/.gitignore: excludes*-content/directories from the repoFixes #315
Checklist
git commit -s).