Skip to content

docs(networks): add versions and releases section#23319

Draft
AztecBot wants to merge 1 commit into
nextfrom
cb/0d25d24ff707
Draft

docs(networks): add versions and releases section#23319
AztecBot wants to merge 1 commit into
nextfrom
cb/0d25d24ff707

Conversation

@AztecBot
Copy link
Copy Markdown
Collaborator

Proposal for how docs.aztec.network/networks looks. The page currently lists each network's live version (e.g. 4.2.0) but does not explain what that version represents, where RCs and nightlies fit, or which version a builder vs operator should pin against. This adds a concise Versions and releases section directly after the Network technical information table, and tightens the existing version note that the new section now supersedes.

Targeted at the two audiences the page already serves: builders shipping on Aztec, and node / sequencer operators. The page already carries the contract-address tables, so this proposal is deliberately conservative on length: ~40 added lines for the new section, plus heading-case fixes and em-dash cleanup the docs style guide already asks for.

What changes

  • New ## Versions and releases section covering:
    • Monorepo single-version model (node, Aztec.nr, aztec.js share the same version).
    • Three release channels (stable, RC, nightly) with examples and an audience column targeted at builders and node operators.
    • The fact that an RC is not newer than its matching stable.
    • Version progression: v4.next → nightlies → merge to v4 → RC(s) → stable → bump; next is parallel for v5.
    • Release notes: pointer to GitHub releases as the authoritative changelog.
    • Cadence: roughly monthly, mid-month, not strictly fixed.
    • "Which version should I use?" split between builders, operators, and people tracking upcoming work, with an explicit note that a public release calendar is on the roadmap.
  • Removes the now-redundant :::note Developer SDK vs Node Versions admonition near the top; its meaning is folded into the new section.
  • Converts the headings on this page from Title Case to sentence case per docs/CLAUDE.md, and replaces em-dashes with commas / colons / parens as the style guide requires.
  • Adds a "Tracking releases?" item to Next steps linking to the new section and to the GitHub releases page.

Open questions

  • Whether to surface internal branch names (v4.next, v4, next) on a user-facing page. They are included because they let readers correlate this page with the GitHub releases page and the nightly tag stream; happy to drop them if too internal for a builder-facing doc.
  • Whether the new section should also be propagated into network_versioned_docs/ snapshots, or only live on the next-release source.

Test plan

  • yarn then yarn start in docs/ and verify the new section renders, anchor links resolve (#versions-and-releases, #network-selection-guide), and the channels table is readable on mobile widths.
  • yarn spellcheck to confirm new terms (e.g. aztec.js, aztec.nr, monorepo, Testnet) are covered by docs-words.txt or already accepted.
  • Sanity-check that the description front-matter still fits the 50-160 char guidance.

Created by claudebox · group: slackbot

@AztecBot AztecBot added the claudebox Owned by claudebox. it can push to this PR. label May 15, 2026
Adds a Versions and releases section to docs/docs/aztec/network/networks.md
explaining the monorepo single-version model, the three release channels
(stable, RC, nightly), the v4.next -> v4 -> RC -> stable progression, the
GitHub releases changelog source, and a builder-vs-operator pinning guide.

Removes the now-redundant Developer SDK vs Node Versions admonition,
applies sentence-case headings and em-dash cleanup per docs/CLAUDE.md, and
adds 'nightlies' to the docs cspell dictionary.
Copy link
Copy Markdown
Contributor

@critesjosh critesjosh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm!

do you think we should say something about version compatibility on this page? e.g. minor and patch version bumps are compatible with previous versions (4.2.0 software and contracts will work with a 4.3.0 network) but major version bumps are breaking (v5 coming in summer will require app developers to upgrade)

@franacc12312
Copy link
Copy Markdown

@critesjosh the thing about that is that it’s not 100% strict, there might still be breaking changes in situations like that. I asked Amin about that exact scenario, and that’s what he said.

@critesjosh
Copy link
Copy Markdown
Contributor

@critesjosh the thing about that is that it’s not 100% strict, there might still be breaking changes in situations like that. I asked Amin about that exact scenario, and that’s what he said.

ok nice, let's now worry about it this pr then. 🚢

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claudebox Owned by claudebox. it can push to this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants