Repository navigation
docs: keep the two dev lines in step, and cut v6.x releases from the v6 line - #25772
Merged
Merged
Conversation
Without COMMIT_TAG (previews, local builds) the legacy macros resolved to next and latest. aztec-node has no next ref, so 38 source links and the aztec-nr Nargo tags pointed nowhere. They now take the ref docs/aztec-node.json pins. Release cuts set COMMIT_TAG and are unchanged. Three @aztec-foundation installs used the Labs macro and named the Labs version in every build; they now use #include_foundation_version_without_prefix.
From 2026-11-04 aztec-node carries v7 on main and v6 on a v6 branch, with hand backports. The dev pin moves to the newest nightly of main's major and is checked to be on main; release cuts pin their tag. The release skills now find hand backports in migration-note triage (TBD and Unreleased) and expect adapted backports on both sides of the content check. update-doc-references reports, without editing, v6 PRs the pin lacks; updating-changelog takes a PR's major from its base. networks.md and support.md no longer name a development branch or aztec-node's nonexistent next.
…rry a v7 line A v6.x release is cut from the dev docs' pages and examples, so it works only while they are v6 content. The pin check now tests that the recorded commit is on v6, and update-doc-references gates PRs into main (v7) instead of PRs into v6.
Prints a sorted hash per page, markdown twin and llms file, the sitemap paths and the search index, so a production build can be diffed against another to show tooling changes leave what docs.aztec.network serves untouched.
…work check_source_urls requires every docs.aztec.network URL in tracked files to resolve, and the fixture's page does not exist.
A line root docs/lines/<line>/ gets its own pin, checkout and toolchain through --line <line>. It never reads AZTEC_NODE_DIR. It refuses another major's tag offline. It gets its own l1-artifacts from npm, checked against the registry integrity. fetch covers every line except in production, and pin installs a line's l1-artifacts before checking. With no docs/lines/ nothing changes.
A page under docs/lines/<line>/ takes its labs/ snippets, source links, COMMIT_TAG and foundation version from its line's pin and checkout. Its #api_ref_version is the folder of the network on its major, and it fails when no network runs that major. Its links into /developers/ and /operate/ move onto the line's instances. A page that quotes another line's examples or l1-artifacts is refused. The lines are processed into processed-docs/lines/<line>/ outside production.
check_source_urls requires every docs.aztec.network URL in tracked files to resolve.
examples/bootstrap.sh --line <line> builds the line's examples with its own pin. nargo takes the topmost Nargo.toml as its workspace, so the build runs in a copy outside the repository that mirrors docs/. The example scripts read DOCS_ROOT instead of a hardcoded docs/. check_doc_references.sh docs/lines/<line> and update_docs.sh --line <line> check the line's references in the line's own checkout. Main's examples build as before; execute stays main-only.
…ng its state check_doc_references.sh also recognises an absolute docs/lines/<line>. The staged examples build no longer creates the line's .aztec-node/l1-artifacts before fetch provisions it.
…ngerprint include_code caches a passed checkout check per pin, not per directory: main's AZTEC_NODE_DIR may name a line's checkout. The production fingerprint keeps <link> tags, so a changed canonical or alternate URL shows. The staged examples build sets its cleanup before copying and refuses a malformed line name. A refused l1-artifacts upgrade keeps the installed package (now tested).
Copies the dev docs' developer and operator pages, their sidebars, the aztec-node pin, the Noir workspace and the example sources into docs/lines/v6, byte for byte. The examples' build tooling (bootstrap scripts, compose file, rebuild patterns) stays main-only, since it builds a line from main's copy. The line's .aztec-node state is gitignored.
A mechanical rewrite of the line's pages only: #include_code paths and references: entries under docs/examples/ now name docs/lines/v6/examples/, and l1-artifacts snippets name the line's provisioned copy in docs/lines/v6/.aztec-node/l1-artifacts/. Every changed line differs from main's only by those prefixes. Prose links into aztec-node and reader setup instructions are unchanged.
Previews serve docs/lines/v6 at /developers-v6 and /operate-v6 as two noindex docs instances; production builds neither. Line pages keep their links on the line, hide the version dropdown and link the API reference of the network that runs v6. Search, llms.txt and the sitemap leave them out. bootstrap.sh checks each line's references and builds its examples.
…ion checks On a line's pages the navbar's Build, Run a Node and Resources links now lead to the line's instances instead of the dev docs. Production no longer spellchecks line pages, and `aztec_node.mts lines` lists none there, so bootstrap's line steps skip in production like fetch does.
…s them On a line's page the Resources dropdown now sees its children's line URLs, so the mobile menu opens on the page it contains. The navbar rewrite is one tested function in docsLine.mjs.
# Conflicts: # docs/scripts/aztec_node.mts # docs/src/__tests__/network_docs.test.js # docs/src/network_docs.js # docs/src/preprocess/include_version.js
scripts/promote_line.sh pins a line to the release tag and serves its pages and pin from docs-developers, docs-operate and the main pin, so a v6.x cut renders the v6 line. It refuses outside the cut worktree, on a dirty docs/, a tag of another major or off the line's branch, and a failed pin, before touching the main paths. Promoted pages keep quoting the line's examples. include_code allows a page to quote another line's files while both pins name one commit.
docs/CLAUDE.md opens with the rule to change both lines unless the code says a change is line-specific, how to port a page's paths, and how to check both. The pin section gives each line its own branch, adds the line cut and line retirement, and drops the stay-on-v6 rule. README.md carries the same for people.
update-doc-references runs by hand, tests a PR's merge commit against every line's pin, maps references in each line and edits each copy whose checkout has the change. updating-changelog reads each line's pin and puts a v6.x entry into both lines, a v7 entry into main only.
Both release skills detect a line cut at Step 2b, when the tag's major has a dev line, and promote the line at Step 2c with promote_line.sh. The examples checks and link checks read the line's examples, Step 12 compares against the line's pin, Step 15 builds and runs the line's examples, and the carry-back applies the promoted pages' repairs to the line, with the release's migration and changelog entries also in main. examples/bootstrap.sh --line keeps one stage across runs when DOCS_LINE_STAGE names it, so a cut can run a line's examples step by step.
- 2a asks for the peeled ref, so 2e compares the commit of an annotated (nightly) tag. - A line cut's pin commit is skipped when nothing drifted: the promotion already carries the pin. - The 8b sweep greps the examples the cut's pages quote ($EXAMPLES). - The changelog checks (10b, 5c) read the line's copy in a line cut. - A nightly is covered by its major's changelog page; a minor release needs its entry first.
A testnet build named the testnet/ API folder even while testnet and mainnet read one version, when the build serves that version's reference under mainnet/ only. A network docs cut builds exactly that way, and its agent readiness check failed on aztec_js_reference.md's link to /typescript-api/testnet/llms.txt. The macro now takes the folder apiReferenceDirs serves for the network's version; line pages keep the folder of the network on their major, and nightly and devnet keep next.
…utorials as readers meet them - The installer, aztec_cli and the local network set NARGO_HOME, AZTEC_HOME and the XDG directories inside CLI_HOME instead of clearing them: noirup's installer writes to NARGO_HOME, so one inherited from the real shell rewrote the real home's noirup. - Step 15.1 reads the Node the release's installer requires from its versions file and runs the installer and the release's commands on it, first on PATH, so the machine's default Node never changes. - Step 15.3 records the publication-day Yarn age gate against each page that hits it, then continues with a pre-approval limited to the tag's own packages; it never turns the gate off. - Step 15.3 walks a line's in-repository tutorials as written before checking their code in the staged layout, so a staged pass never hides a reader's failure.
…e commit The v6 line's token bridge and Aave bridge tutorials clone a third-party Hardhat starter and then run yarn, which runs that repository's postinstall. Check out the reviewed commit right after entering the clone, matching the change to main's pages, so later upstream changes never run on a reader's machine.
…ranch promote_line.sh compared the tag with the line's branch before pinning, in the repository the line named before. A tag moved between that compare and the pin could promote a commit never checked. Compare the commit the pin recorded, in the repository the pin enforces, and restore the line when that check refuses.
A release cut freezes #api_ref_version into its snapshot at Step 11, before 11b maps the new version. Resolving against the developer config as it was named mainnet's folder for a testnet release that splits from mainnet, so the snapshot linked the older version's API. Resolve against the config with the release type reading the version being built. A network-only cut leaves the developer versions alone, so its builds must keep linking the folders served now: release-network-docs sets KEEP_DEVELOPER_VERSIONS=1, and without it agent readiness fails the build.
The key named the release type, COMMIT_TAG and DOCS_COMMIT but not CONTEXT, the per-type tags or KEEP_DEVELOPER_VERSIONS, so a production build could restore a preview build's output (with the dev docs and the lines) from the cache.
cspell reads a line's pages only under processed-docs/, so a bare yarn spellcheck after editing one checks a stale copy or none.
asterite
approved these changes
Nov 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs changes now go into both the v6 and v7 lines unless they only apply to one: CLAUDE.md, the README and the docs skills say so, and the release skills can cut a v6.x docs release from the v6 line. A full practice run of both release skills on a v6 nightly also fixed the API reference links of a release, the release CLI's setup, and how tutorials are checked. The v6 line's bridge tutorials pin the Hardhat starter like main's do. Production output is unchanged.