docs(release-process): fix wrong monorepo paths, invalid bash, and stale release-script flags

[GigaHierz]

Supersedes #2139. Same intent, rebuilt on current main, with @martinvol credited as co-author.

Why not just merge #2139

That branch was cut in February and main has moved. Merging it as-is would revert four things main has since fixed:

main has	#2139 would restore
description: frontmatter	og:description: (#2239 already migrated it)
celo-monorepo setup link pinned to 045aa0061 + .nvmrc	the older unpinned SETUP.md link
docs.openzeppelin.com/upgrades-plugins/1.x/proxies#...	the version-less URL
NETWORK=${"anvil"|"celo-sepolia"|"mainnet"}	drops the anvil option

Its Baklava/Alfajores→Celo Sepolia edits are also already on main via #2175, and the release-timeline table on main is correct — the T+2w/T+3w duplication that appears when you rebase #2139 is an artifact of the stale base, not a real defect.

So this PR takes only the parts of #2139 that main still needs.

Verified against celo-org/celo-monorepo

$ gh api repos/celo-org/celo-monorepo/contents/packages/what-is-celo
404 Not Found                                   # the path the page documents

$ gh api repos/celo-org/celo-monorepo/contents/packages/protocol/releaseData --jq '.[].name'
README.md  extraTransactions  initializationData  nonstandard  versionReports

$ gh api repos/celo-org/celo-monorepo/contents/.circleci
404 Not Found                                   # moved to GitHub Actions

$ gh api .../contents/.github/workflows/celo-monorepo.yml | grep RELEASE_TAG
32:  RELEASE_TAG: core-contracts.v17

packages/what-is-celo/about-celo-l1/protocol/releaseData/ is a bad find-and-replace from an old docs migration — the docs path got substituted into a source-tree path.

Bash that could not run

• ${N-1} is not arithmetic. It is parameter expansion with a default, so with N unset it evaluates to the literal N and PREVIOUS_RELEASE came out as core-contracts.vN. Now $((N-1)).
• NETWORK=${"anvil"|"celo-sepolia"|"mainnet"} is a syntax error, not a placeholder. Now a real assignment with the options in a trailing comment.
• Six blocks referenced variables they never defined — $N, $PREVIOUS_RELEASE, $RELEASE_CANDIDATE, $PRIVATE_KEY. Only the first block on the page defined anything, so copying any later block failed. Each block now stands alone, per AGENTS.md section 5. Examples use N=18, the next release after the core-contracts.v17 currently pinned in the workflow.

Script flags and generated filenames

-r and -p no longer name files the scripts write themselves; -k is required by release:make. The generated names (report-$PREVIOUS_RELEASE-$RELEASE_CANDIDATE.json, $NETWORK-$PREVIOUS_RELEASE-libraries.json, proposal-$NETWORK-$RELEASE_CANDIDATE.json) are now stated where they are produced and reused where they are consumed, including in the celocli governance:propose call.

Also

export const N = "N" Docusaurus leftover removed, and three typos: Vaildator, valildator, EXCECUTED.

Verification

$ npx mintlify broken-links
success no broken links found

I have not touched the flag/filename semantics beyond what #2139 asserted — those come from the release-script owner and I could not verify them against the scripts themselves, so they are worth a second pair of eyes from @martinvol.

[palango]

Most of this is right, and more of it is right than the body claims. You wrote that you could not verify the flag and filename semantics against the scripts, so I did: they are correct, including one subtlety I doubt was luck. What stops me approving is the layer underneath. The commands those flags hang off were deleted from celo-monorepo, so the page still cannot be followed end to end.

The blocker: four dead script names

packages/protocol/package.json on master defines only release:check-versions, release:check-versions:foundry, release:make:foundry, release:verify-deployed:foundry, release:check-opcodes and release:determine-release-version. The Truffle entries went in 6ce74bb32, and they are absent at tag core-contracts.v17 too, so this is not master-only drift.

line	page says	needs to be
95, 191	yarn release:verify-deployed	release:verify-deployed:foundry
145	yarn release:make	release:make:foundry
129	yarn release:check-versions	release:check-versions:foundry
180	yarn release:verify-release	deleted, no :foundry sibling

129 is the one that hides. The package.json key still exists, so a grep finds it, but check-versions.sh calls build_tag and release-lib.sh now defines only build_tag_foundry. Under set -euo pipefail it dies before compiling anything.

For 180, packages/protocol/RELEASE_PROCESS_FOUNDRY.md maps release:verify-release to "use verify-deployed with --proposal", and verify-deployed-forge.sh accepts both -p and -i, so the substitution is mechanical:

yarn release:verify-deployed:foundry -p "upgrade_proposal.json" -b $RELEASE_CANDIDATE -n $NETWORK -f -i initialization_data.json

Read that file before the next push. Its opening table is this exact mapping, and it would have caught all four. The page probably ought to link it, since it is the release owners' own doc. Stale prose mentions of the old names sit on 87, 98, 132, 170 and 185.

What's right

• packages/what-is-celo/... 404s; packages/protocol/releaseData/initializationData/ holds release1.json through release17.json. Your read of the bad find-and-replace is right.
• .circleci is gone, and .github/workflows/celo-monorepo.yml:32 is RELEASE_TAG: core-contracts.v17.
• NETWORK=${"anvil"|"celo-sepolia"|"mainnet"} really was a syntax error, and all three names in the replacement comment resolve in truffle-config-parent.js.
• Dropping -p: make-release-foundry.sh:57 hard-errors on any -p path and derives proposal-$NETWORK-$BRANCH.json itself at line 61. Dropping -r: same shape in check-versions-foundry.sh, which builds report-$BRANCH-$NEW_BRANCH.json. Adding -k: getopts 'b:k:i:l:n:p:r:u:sa:', mandatory at line 49.
• -l "$NETWORK-$PREVIOUS_RELEASE-libraries.json" is not merely plausible, it is the only value that passes. validate_libraries_filename rejects anything that is not the previous release's file.

The fix here is four script renames and a tag. No command needs reworking.

Smaller things

Line 56 still carries the wrong tag. You corrected the file path in that sentence and left celo-core-contracts-v${N}.pre-audit sitting next to it. That family stops at v7 upstream, and every pre-audit tag since is core-contracts.v${N}.pre-audit, which is what step 2 two lines above already creates.

On line 136, "(Use -d to dry-run the deploy)" now contradicts the -k you added on 145. -d belonged to the deleted Truffle script. The Foundry one has no dry-run at all, so drop the parenthetical or point at -u against a local anvil fork instead.

Line 156 is the one block that never got a preamble, and this PR is what broke it. Main had the literal "proposal.json". You replaced that with "proposal-$NETWORK-$RELEASE_CANDIDATE.json" and defined neither variable, so copied on its own it resolves to proposal--.json. The block was copy-safe before and is not now.

Lines 144 and 145: PRIVATE_KEY= empty plus unquoted -k $PRIVATE_KEY word-splits down to a bare trailing -k, and getopts bails before the script's own "Need to set the private key" message ever prints. Quoting fixes that. A visible placeholder would be better still, and a mainnet deployer key in argv deserves a sentence of warning.

Line 171 says "the proposal.json you fetched in the step prior", naming a file that now appears nowhere else on the page. The artifact fetched in that step is upgrade_proposal.json.

Line 69, the prerequisites callout, still says yarn install plus yarn build is a complete setup. Every block you rewrote runs through forge build, and the deploy block wants cast and jq. It predates you, but this PR is what moved the page onto the Foundry contract.

One nit: only the first block says # Run from packages/protocol. The other five need it too, since the scripts source relative paths and -i takes a repo-relative path.

The body

Six statements do not hold, and reviewers approve on the strength of the body:

1. ${N-1} is not "the literal N". It is ${parameter-word}: unset gives core-contracts.v1, and with N=18 it gives core-contracts.v18, the release being prepared. Silently wrong rather than obviously wrong, which is a better argument for your fix than the one you made.
2. The OpenZeppelin row is inverted. Main has the version-less URL and it returns 200. Fix smart contracts release process docs #2139's branch is the one carrying /1.x/, which 404s. Anyone acting on the row as written would swap a working link for a dead one.
3. Of the four claimed reverts, one is real. Fix smart contracts release process docs #2139 touches a single file, and on three of those four lines its head is byte-identical to its merge base, so a merge would revert nothing. Only the anvil option genuinely conflicts.
4. "Only the first block on the page defined anything" is not what the diff shows. Four of the five later blocks defined their own variables. What none of them defined was N, and $PRIVATE_KEY was not on the page at all before this PR.
5. "Each block now stands alone" is false for line 156, per above.
6. export const N = "N" arrived in b555aecb "remove: removed docusaurus (#2040)", so the Mintlify migration wrote it rather than inheriting it. Removing it is still safe: every ${N} on the page sits inside an inline-code span or a fence, and MDX evaluates neither.

Happy to push the renames myself if that is easier than another round.