docs: document git-ref-based docs versioning - #6558
docs: document git-ref-based docs versioning#6558devin-ai-integration[bot] wants to merge 8 commits into
Conversation
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
|
|
||
| ## Build a version from a git ref | ||
|
|
||
| Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, API definitions, and committed library output from it, composed with the current branch's theme, shell, and `versions` metadata. |
There was a problem hiding this comment.
You can just build that versions content
There was a problem hiding this comment.
Trimmed to "builds that version's content from it" in 4fd1354 (same in the changelog entry).
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
|
||
| Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. | ||
|
|
||
| At the ref, Fern builds the navigation from that commit's `versions[0].path`, falling back to its top-level `navigation`. The ref's own `versions` list isn't followed, so older versions declared there are ignored. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. |
There was a problem hiding this comment.
does versions[0].path mean anything for an end user?
There was a problem hiding this comment.
No — that was internal shorthand. Reworded in 305a279: "If the ref's own docs.yml is versioned, Fern builds its default version (the first entry in its versions list) and ignores the rest; otherwise it builds the ref's top-level navigation."
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
| - display-name: Latest | ||
| path: ./versions/latest.yml # built from the working tree | ||
| - display-name: v2 | ||
| ref: v2.0.0 # built from the tag v2.0.0 |
There was a problem hiding this comment.
add an example of a branch as well
There was a problem hiding this comment.
Added in 67d6c50 — the example now shows a branch (release/v2) alongside the tag (v1.0.0).
| ``` | ||
| </CodeBlock> | ||
|
|
||
| A version entry sets either `path` or `ref`, never both. Declaring both fails `fern check`. |
There was a problem hiding this comment.
dont think u need to explicitly mention
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
|
||
| Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content. | ||
|
|
||
| If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build. |
There was a problem hiding this comment.
shallow CI checkouts are backfilled with a targeted fetch. If a version's library reference output is missing at the ref, Fern warns and skips that section rather than failing the build.
^ not necessary to add
There was a problem hiding this comment.
Removed both in e87a1e3; the paragraph now ends at "Publishing requires git and access to the remote."
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
🌿 Preview your docs: https://fern-preview-devin-1786039614-git-ref-versioning-docs.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| <CodeBlock title="docs.yml"> | ||
| ```yaml {5} | ||
| versions: | ||
| - display-name: Latest |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'Latest' that become outdated
| ```yaml {5} | ||
| versions: | ||
| - display-name: Latest | ||
| path: ./versions/latest.yml # built from the working tree |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.
Tip: disable this comment in your organization's Code Review settings.
2 participants
Summary
Documents
ref:on adocs.ymlversion entry (fern#17288) as a new section on the existing Versions page, plus a changelog entry.The section is deliberately opinionated:
ref:is framed as the way to serve frozen versions archived at a past release, not versions under active maintenance, becausefern docs devpreviews working-tree versions only and ref-backed content is built at publish. The recommended shape is a singlemain/masterbranch holding current docs and the fullversions:list, with past releases archived at tags — the alternative to long-lived version branches.Also notes that tags/SHAs are immutable while branch refs re-resolve on every publish, and how Fern picks what to build at the ref (the ref's default version if its
docs.ymlis versioned, otherwise its top-levelnavigation).Link to Devin session: https://app.devin.ai/sessions/bd012060ec3549629c8a073910ae761d