fix(fern): build release snapshots from tagged commits

[nealvaidya]

Summary

• build versioned Fern pages and navigation from the tagged commit instead of the continuously synchronized pages-dev and dev.yml
• add an explicit force_rebuild path plus tagged-inventory, navigation-target, and Fern configuration checks before commit/publish
• add a local release dry-run under fern/ and update the docs workflow guidance

The previous workflow checked out only docs-website, so a release tag could publish whatever content happened to be on main under the version label. This change checks out the requested tag alongside docs-website, uses the tag's raw docs, navigation, and converter, and converts callouts exactly once.

This PR does not force-rebuild any existing snapshot. Historical repository-relative link debt and any curated v1.2.1 redirects will be handled separately.

Fixes #11135

Validation

• PYTHON=.venv/bin/python fern/release_dryrun.sh v1.2.1
• fern check — 0 errors
• fern docs broken-links — passed
• bash -n fern/release_dryrun.sh
• workflow YAML parsed with PyYAML
• codespell on changed docs and shell files
• npm test in .github/scripts — 20/20 filter tests passed
• verified fern/release_dryrun.sh matches the existing docs: fern/** CI filter
• git diff --check

Summary by CodeRabbit

• New Features

  • Added a local dry-run option for versioned docs releases, making it easier to validate a tagged release before publishing.

• Bug Fixes

  • Improved versioned documentation publishing to better handle rebuilds, prevent accidental overwrites, and ensure published snapshots match the tagged docs content.

• Documentation

  • Updated release and publishing docs to reflect the new version snapshot flow, path rewriting behavior, and dry-run steps.

[github-actions]

🌿 Fern Docs Preview: https://nvidia-preview-019f24ba-1986-7334-af41-8a0b9c91109c.docs.buildwithfern.com/dynamo/dev

[devin-ai-integration]

Devin Review found 2 potential issues.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 25ac5c82-3b90-48e1-9e62-34b6f1739cd7

📥 Commits

Reviewing files that changed from the base of the PR and between 54e5037 and a6031f4.

📒 Files selected for processing (3)

• .github/workflows/fern-docs.yml
• docs/README.md
• fern/release_dryrun.sh

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/README.md
• .github/workflows/fern-docs.yml

---

Walkthrough

This PR fixes the Fern release-version workflow to build versioned documentation snapshots from the tagged source commit instead of pages-dev, adding a force_rebuild input, updated inventory/nav validation, revised documentation, and a new local dry-run script.

Changes

Tag-based version release rebuild

Layer / File(s)	Summary
Workflow dispatch force_rebuild input .github/workflows/fern-docs.yml	Adds a workflow_dispatch boolean input force_rebuild (default false) controlling overwrite of existing version snapshots.
Tag-based snapshot build and validation .github/workflows/fern-docs.yml	Checks out the source repo at the tag, gates overwriting via force_rebuild, rebuilds fern/pages-$TAG from the tag's docs/, runs callout conversion and link pinning against the tag checkout, generates fern/versions/$TAG.yml from the tag's docs/index.yml, updates fern/docs.yml version entries and default path/display-name, validates file inventory and nav targets, runs fern check, and publishes from docs-checkout/fern.
Documentation updates docs/README.md, docs/documentation-style-guide.md	Revises snapshot behavior description, Job 3 step sequence, publishing diagram, and adds a "Dry-run a version release" section.
Local dry-run script fern/release_dryrun.sh	Adds a script that validates tooling/tag format, creates temporary git worktrees, rebuilds fern/pages-$TAG via rsync, rewrites GitHub links, runs callout conversion, generates fern/versions/$TAG.yml, updates fern/docs.yml, compares Fern CLI versions, validates inventory and nav targets, and runs fern check.

Estimated code review effort: 4 (Complex) | ~60 minutes

Related issues: Fixes docs(fern) version snapshots being built from pages-dev instead of the tagged commit (#11135).

Suggested labels: documentation, ci, fern

Suggested reviewers: none identified

🐰 A tag once cut, a page once built,
No more from dev where snapshots wilt,
Now checked, now rsync'd, line by line true,
The dry-run hums before the push comes through,
Hop, hop — the release, at last, in view.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is missing required template sections, including Overview, Details, Where should reviewer start?, and a proper Related Issues section.	Add the missing template sections and include a complete Related Issues block with the correct linked or unlinked choice.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: building release snapshots from tagged commits.
Linked Issues check	✅ Passed	The changes match #11135 by building pages and navigation from the tag, converting once, and validating before publish.
Out of Scope Changes check	✅ Passed	The extra dry-run script, force_rebuild path, and docs updates align with the PR objective and are not unrelated scope creep.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

_{Comment @coderabbitai help to get the list of available commands.}

[nealvaidya]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[dmitry-tokarev-nv]

Automated review — PR #11140

Reworks the release-version job to build the version snapshot from the tagged commit's docs/ (via a new source-checkout) instead of pages-dev, adds a force_rebuild dispatch input and a pre-publish validation gate (inventory diff + nav-target existence + fern check), and adds fern/release_dryrun.sh to reproduce the job locally. Core mechanics look sound — the rsync exclusions and yq path transforms are byte-identical to the proven dev-sync path, and the yq ${1} capture works. The notes below are robustness/fidelity gaps, not miscompiles; most are attached inline.

Also: no concurrency group / no push retry (workflow-level — no clean inline anchor)

release-version checks out docs-website at job start and ends with git push origin docs-website, with no concurrency: group anywhere in the workflow and no git pull --rebase/retry. If two version tags land close together (or a tag push overlaps a workflow_dispatch), both jobs branch from the same head and the second push is rejected non-fast-forward — that version's snapshot never reaches docs-website and needs a manual re-run. Consider a concurrency: { group: fern-release-docs-website, cancel-in-progress: false } and/or a rebase-and-retry around the push. (Pre-existing, but this PR rewrites the whole job.)

Considered and dropped

The ^([a-zA-Z]) rewrite skipping non-letter paths (all current index.yml paths start with letters); the inventory-diff vs rsync digest-depth mismatch (no nested digest/ exists); fern-api@…@null (version key present); and the HAVE_FERN asdf/volta detection gap (cosmetic).

[dmitry-tokarev-nv]

Nice one!
Thank you for resolving all comments too