Add Fern Replay docs and migration guide#5497
Conversation
Introduces customer-facing documentation for Fern Replay ahead of the broader launch. Replay preserves SDK customizations across regenerations via 3-way merge, complementing `.fernignore`'s file-level protection. - custom-code.mdx: new "Preserving customizations with Replay" section, with the existing `.fernignore` section lightly reframed so the two tools coexist clearly. Early Access callout mirrors Autorelease's rollout pattern. - replay-migration.mdx: 5-phase guide for switching SDK generation from `release` or `push` mode to `pull-request` mode (a Replay requirement). Hidden in nav until launch. - sdks.yml: hidden nav entry for the migration page. - generators-yml-reference.mdx: `replay` (global + per-generator) opt-out config, mirroring the `autorelease` reference shape.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| Fern provides two complementary tools for keeping your customizations safe across regenerations: **Replay** for line-level edits to generated files, and **`.fernignore`** for files you own end-to-end. | ||
|
|
||
| ## Preserving customizations with Replay |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Preserving customizations with Replay' should use sentence-style capitalization.
|
|
||
| Replay requires `pull-request` output mode. If your SDK uses `release` or `push` mode, see the [migration guide](/learn/sdks/overview/replay-migration) for the switch. | ||
|
|
||
| ### Disable Replay |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Disable Replay' should use sentence-style capitalization.
|
|
||
| ## Phase 3: Decouple publishing from generation (optional) | ||
|
|
||
| If you want to control publishing separately from generation, keep your publish workflow out of Fern's generation cycle: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'separately' if it's not important to the meaning of the statement.
- Lowercase 'replay' in three headings per FernStyles.Headings (matches the 'Disable autorelease' convention in autorelease.mdx) - Rephrase Phase 3 intro to drop the unnecessary 'separately' adverb flagged by FernStyles.Adverbs
Replay is generally available at launch (org gate is being removed), not in early access. Update both pages accordingly: - Replace Early Access callouts with a Note stating the actual customer requirement: latest Fern CLI and SDK generator versions - Drop "Contact us" CTAs (Replay isn't opt-in) - Migration guide's "Before you start" becomes a 2-bullet checklist: install the Fern GitHub App + run `fern upgrade`
| ## Preserving customizations with replay | ||
|
|
||
| <Note> | ||
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
| --- | ||
|
|
||
| <Note> | ||
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
| ## Before you start | ||
|
|
||
| - Install the [Fern GitHub App](https://github.com/apps/fern-api) on your SDK repositories. | ||
| - Update to the latest Fern CLI and SDK generator versions (`fern upgrade`). |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
…into tanmay/replay-docs
| ## Line-level edits with Replay | ||
|
|
||
| <Note title="Requirements"> | ||
| Replay is on by default for SDKs using [`pull-request` output mode](/learn/sdks/reference/generators-yml#pull-request). To enable Replay on an SDK that's currently on `release` or `push` mode, switch to `pull-request` mode via the [migration guide](/learn/sdks/overview/replay-migration). |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated
| <Note title="Requirements"> | ||
| Replay is on by default for SDKs using [`pull-request` output mode](/learn/sdks/reference/generators-yml#pull-request). To enable Replay on an SDK that's currently on `release` or `push` mode, switch to `pull-request` mode via the [migration guide](/learn/sdks/overview/replay-migration). | ||
|
|
||
| Replay requires the latest Fern CLI and SDK generator versions — run `fern upgrade` to make sure you're current. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
| --- | ||
|
|
||
| <Note> | ||
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. | ||
| </Note> | ||
|
|
||
| This guide migrates an SDK from `release` or `push` output mode to `pull-request` output mode — the mode required to enable [Fern Replay](/learn/sdks/overview/custom-code#line-level-edits-with-replay). Only follow it if your SDK is currently on `release` or `push` mode and you want to switch in order to use Replay. SDKs already using `pull-request` mode have Replay on by default; no migration is needed. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. | ||
| </Note> | ||
|
|
||
| This guide migrates an SDK from `release` or `push` output mode to `pull-request` output mode — the mode required to enable [Fern Replay](/learn/sdks/overview/custom-code#line-level-edits-with-replay). Only follow it if your SDK is currently on `release` or `push` mode and you want to switch in order to use Replay. SDKs already using `pull-request` mode have Replay on by default; no migration is needed. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.Wordiness] Consider using 'to' instead of 'in order to'.
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. | ||
| </Note> | ||
|
|
||
| This guide migrates an SDK from `release` or `push` output mode to `pull-request` output mode — the mode required to enable [Fern Replay](/learn/sdks/overview/custom-code#replay). Only follow it if your SDK is currently on `release` or `push` mode and you want to switch in order to use Replay. SDKs already using `pull-request` mode have Replay on by default; no migration is needed. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated
| Replay requires the latest Fern CLI and SDK generator versions. Run `fern upgrade` to make sure you're current. | ||
| </Note> | ||
|
|
||
| This guide migrates an SDK from `release` or `push` output mode to `pull-request` output mode — the mode required to enable [Fern Replay](/learn/sdks/overview/custom-code#replay). Only follow it if your SDK is currently on `release` or `push` mode and you want to switch in order to use Replay. SDKs already using `pull-request` mode have Replay on by default; no migration is needed. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.Wordiness] Consider using 'to' instead of 'in order to'.
2 participants
Summary
Customer-facing docs for the Fern Replay GA launch. Replay preserves SDK customizations across regenerations via 3-way merge, complementing
.fernignore's file-level protection.custom-code.mdx— adds a## Preserving customizations with replaysection between the opening and the existing.fernignoresection. Lightly reframes the.fernignoreintro so the two tools coexist clearly (Replay for line-level edits,.fernignorefor full-file ownership). The Note on customer requirements: latest Fern CLI + SDK generator versions (fern upgrade).replay-migration.mdx(new) — 5-phase customer guide for switching SDK generation fromreleaseorpushmode topull-requestmode (a Replay requirement). Includes a quick-disable rollback option (delete .fern/replay.lock) and a full revert path. Hidden in nav until launch.sdks.yml— adds a hidden nav entry for the migration page, slotted betweencustom-codeandcapabilities(matches the Autorelease slot pattern).generators-yml-reference.mdx— addsreplayreference entries (global + per-generator) for opt-out config. Mirrors the existingautoreleaseshape.Test plan
Coordination with launch
This PR should merge in coordination with the org-gate removal in fiddle (`replay-enabled-orgs.json`), since the docs claim Replay is GA. Merging earlier than that would tell customers Replay is ready when it isn't yet rolled out to their org.
On launch day, one additional change flips the migration guide into public nav: in `sdks.yml`, change `hidden: true` to `hidden: false` on the Migrating to Replay entry. The custom-code Replay section goes live the moment this PR merges.