Regenerate Changelog on New Release

[MarcusSorealheis]

Description

Today, the Changelog in the docs site is frozen at 1.3.0. WE'd like for each release to be covered in accordance with the canonical changelog.

Fixes #2499

Type of change

Please delete options that aren't relevant.

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

How Has This Been Tested?

web && bunx turbo run build --filter=@nativelink/docs 2>&1 | tail -4

Checklist

• Updated documentation if needed
• Tests added/amended
• bazel test //... passes locally
• PR is contained in a single commit, using git amend see some docs

---

This change is 

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nativelink	Ready	Preview, Comment	Jul 3, 2026 11:10pm
nativelink-aidm	Ready	Preview, Comment	Jul 3, 2026 11:10pm

[corcillo]

@MarcusSorealheis Approved but appears to be a couple bugs via clanker review, #1 is most important

Review: PR #2500 — "Regenerate Changelog on New Release"

Findings, most severe first (all verified; several reproduced empirically against the real files and toolchain):

1. web/turbo.json:10 — In exactly the environment the fetch fallback exists for, the turbo cache key contains no changelog signal at all (CONFIRMED via turbo 2.9.15 fixture). When the repo root isn't mounted, $TURBO_ROOT$/../CHANGELOG.md silently matches nothing, and VERCEL_GIT_COMMIT_SHA — which determines the fetched content — isn't declared in the task's env. A release merge touching only root files then gets a remote-cache hit that replays the previous .next output, publishing the stale page: the exact bug class the PR fixes, reintroduced by one Vercel config combination. Fix: declare VERCEL_GIT_COMMIT_SHA in the task env (cheap and sufficient).
2. web/apps/docs/scripts/gen-changelog.mjs:99 — The escape set is incomplete for the MDX grammar it defends against, and the page is emitted as .mdx when .md would eliminate most of the break class (CONFIRMED). Reproduced: a prose line starting with import fails MDX compile with an acorn error ("manual changelog adjustments" are explicitly anticipated by CONTRIBUTING.md), while the same input compiles fine as .md format — which fumadocs-mdx 15 already supports by file extension. Emitting changelog.md removes the {}/JSX/ESM hazards wholesale; only <-escaping must stay.
3. web/apps/docs/scripts/gen-changelog.mjs:99 — escapeProse is not backslash-aware (CONFIRMED by repro): input <TERM> becomes \, which MDX parses as escaped-backslash + raw JSX tag → build failure. No such sequence exists in today's changelog (latent), but one shell-escape-flavored commit subject breaks every subsequent deploy. Fix: escape backslashes first or use a backslash-aware replacement.
4. web/apps/docs/content/docs/reference/meta.json:5 — The meta entry now points at a gitignored file that only exists after the wrapper scripts run, and fumadocs-core 16.9.3 silently skips unresolved entries (CONFIRMED by loader inspection). Anyone invoking next build/next dev directly — IDE launch config, an overridden Vercel build command — publishes docs with the changelog page silently missing and a 404 at /reference/changelog, with zero failing signal.
5. web/apps/docs/scripts/gen-changelog.mjs:116 — GIT_CLIFF_MARKER_LINES is byte-coupled to cliff.toml's current templates and fails visibly-but-silently on drift (CONFIRMED end-to-end): rewording the footer comment makes the published page render literal junk with no build error. A whole-line /^$/ strip is equally safe — anything not matching still gets neutralized by the escaper — and removes the cross-file coupling. (Also: the entry is dead; the header slice removes it before the Set is ever consulted.)
6. web/apps/docs/scripts/gen-changelog.mjs:99 — Reuse: the script re-implements MDX escaping that already exists one directory away in scripts/lib/schema-to-mdx.mjs (sanitizeMarkdown/escapeMdxText, entity-based with matched-fence handling), and hand-rolls repo-root discovery while sibling gen-config-reference.mjs uses git rev-parse --show-toplevel. Two divergent escapers and two root-discovery rules in the same scripts directory means every future fix must be found and applied twice.
7. web/apps/docs/scripts/gen-changelog.mjs:138 — The page mirrors the entire changelog with no cap: measured 308 KB of MDX, 31 releases back to pre-GA, ~630 KB compiled, an on-the-order-of-a-megabyte page payload, and thousands of commit subjects ingested into the docs search index where they'll dominate results for terms like "worker" or "redis". Truncating to the last N releases with a link to GitHub for full history bounds all three costs.
8. web/apps/docs/scripts/gen-changelog.mjs:136 — The inFence tracker is dead code with a fail-open failure mode (CONFIRMED: cliff.toml's body template can only emit ## /### /- lines; the real changelog contains zero fences). If a fence-like line ever did appear, one unmatched toggle disables escaping — the file's self-described "security boundary" — for the entire rest of the file. Dropping the tracker is both simpler and safer.

Checked and clean: the three marker lines exactly match today's cliff.toml output; the generated page from the real changelog has zero unescaped </{/} and no surviving HTML comments; turbo hashing of the out-of-root input works correctly when the file is on disk; the fail-loud fetch fallback is documented intended design (a verifier refuted "make it soft-fail" as contrary to the PR's stated contract — though the HTTP-error path's message could usefully repeat the Vercel-toggle instruction); and no CLAUDE.md governs the changed paths. One honorable mention that didn't make the cut: .github/workflows/web.yaml only builds on pull_request, so a changelog edit landing on main outside a PR is first validated by the production Vercel deploy itself.