fix(release): align Release PR title and checklist (#10994)

Author: gustavovalverde

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 # Release workflow: crate publishing and GitHub Release creation.
 #
-# Changelog generation is handled by release-plz + git-cliff.
+# Changelogs are authored in source PRs and finalized before release.
 #
 # Pipeline:
 #   push to main                  → creates/updates the single Release PR
@@ -27,7 +27,7 @@ jobs:
   #
   # Runs on every push to main. Detects changed crates by comparing local
   # source against crates.io, bumps versions based on conventional commits,
-  # generates per-crate changelogs, and opens/updates a single Release PR.
+  # and opens or updates a single Release PR.
   release-pr:
     name: Create or update Release PR
     if: github.event_name == 'push'
@@ -56,11 +56,42 @@ jobs:
           persist-credentials: false
           token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
       - name: Create or update Release PR
+        id: release-plz-pr
         uses: release-plz/action@e8792575c7f2366cf6ff3ccc33ead9ace5b691c7 #v0.5.130
         with:
           command: release-pr
         env:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+      - name: Add zebrad version to Release PR title
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+          RELEASE_PRS: ${{ steps.release-plz-pr.outputs.prs }}
+        run: |
+          set -euo pipefail
+
+          ZEBRAD_RELEASE_PR="$(jq -c '
+            map(select(any(.releases[]?; .package_name == "zebrad")))
+            | first // empty
+          ' <<< "${RELEASE_PRS:-[]}")"
+
+          if [ -z "${ZEBRAD_RELEASE_PR}" ]; then
+            echo "No zebrad release in release-plz output; keeping the generated title."
+            exit 0
+          fi
+
+          PR_NUMBER="$(jq -r '.number' <<< "${ZEBRAD_RELEASE_PR}")"
+          VERSION="$(jq -r '
+            .releases[] | select(.package_name == "zebrad") | .version
+          ' <<< "${ZEBRAD_RELEASE_PR}")"
+
+          if [ -z "${PR_NUMBER}" ] || [ "${PR_NUMBER}" = "null" ] || [ -z "${VERSION}" ] || [ "${VERSION}" = "null" ]; then
+            echo "::error::release-plz did not return both the PR number and zebrad version: ${ZEBRAD_RELEASE_PR}"
+            exit 1
+          fi
+
+          gh pr edit "${PR_NUMBER}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "chore: release v${VERSION}"
 
   # ── Stage 2: Publish crates and create the public zebrad release ────────
   #

.release-plz.toml

@@ -28,22 +28,51 @@ release_commits = "^(feat|fix|perf|refactor|build)"
 pr_labels = ["A-release"]
 
 pr_body = """
-## Review the Release PR
-
-- [ ] Version bumps match user-visible changes for each crate (`major` for network upgrades or breaking API, `minor` for new API/behavior/RPC/config, `patch` otherwise)
-- [ ] Each changed crate's `[Unreleased]` entries follow the Changelog Guidelines (operator-focused in the root `CHANGELOG.md`, crate-consumer-focused per crate)
-- [ ] `[Unreleased]` has been renamed to the release heading (`## [Zebra <version>]` in the root, `## [<version>]` per crate)
-- [ ] No git dependencies remain in crates publishing to crates.io (`check-no-git-dependencies`)
-- [ ] Any required checkpoint, end-of-support height, README, or operational changes already landed
-- [ ] `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` are configured at repository or organization scope
-- [ ] Merge only when crates should publish and the public `zebrad` GitHub Release should be created
-
-## Release Summary
+## Release summary
 
 {% for release in releases %}
-- `{{ release.package }}`: {% if release.previous_version and release.previous_version != release.next_version %}{{ release.previous_version }} -> {% endif %}{{ release.next_version }}
+- `{{ release.package }}`: {% if release.previous_version and release.previous_version != release.next_version %}{{ release.previous_version }} → {% endif %}{{ release.next_version }}
 {%- endfor %}
 
+## Review this release
+
+Review the latest commit after all intended changes have landed on `main` and release-plz has finished updating this PR.
+
+### Release prerequisites
+
+- [ ] No unintended prerelease dependency versions remain.
+
+For releases that include `zebrad`:
+
+- [ ] A full sync completed after the latest state change, or no new full sync is required.
+- [ ] Mainnet and Testnet checkpoints are current for this release.
+
+### Release contents
+
+- [ ] If `zebrad` is included, the root changelog covers every operator-visible change since the previous `zebrad` release.
+- [ ] Each crate changelog covers every consumer-visible change since that crate's previous release.
+- [ ] Changelog entries describe the final behavior, use the correct category, and link the relevant pull requests.
+
+### Versions
+
+- [ ] If `zebrad` is included, its proposed version follows the release policy, and its stable or prerelease status is correct.
+- [ ] Each crate version follows Cargo SemVer for its API and behavior changes, and dependency-only releases use the smallest required bump.
+- [ ] Every release heading matches the corresponding version in the release summary.
+
+### Release data and documentation
+
+For releases that include `zebrad`:
+
+- [ ] The end-of-support height matches the intended release date.
+- [ ] Network-upgrade activation heights and the minimum network protocol version are correct, when applicable.
+- [ ] README, installation, compatibility, and operational documentation match the release.
+
+### Approval
+
+- [ ] This exact commit is ready to publish.
+
+Merging this PR publishes the listed crates and creates their git tags. If `zebrad` is listed, the workflow also creates the public GitHub Release and starts the binary, Docker, and GCP release workflows.
+
 ---
 This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).
 """

book/src/dev/release-process.md

@@ -128,13 +128,12 @@ To help ensure that you have sufficient time and a clear path to update, this is
 
 ## Release candidate & release process
 
-Stable releases are generated from `main` by `release-plz`.
-After each push to `main`, release-plz opens or updates a Release PR when it finds releasable crate changes.
-The generated Release PR contains version bumps and changelog updates for the crates that changed.
-The Release PR is the manual review gate: after maintainers review and merge it, the release workflow publishes crates to crates.io, creates the release git tags, and creates the public `zebrad` GitHub Release.
+Releases are generated from `main` by `release-plz`. After each push to `main`, release-plz opens or updates a Release PR when it finds releasable crate changes. The generated PR contains the proposed version bumps and a summary of the crates to publish; when it includes `zebrad`, the PR title identifies the proposed `zebrad` version.
+
+The Release PR is the manual review gate. After maintainers review and merge it, the release workflow publishes crates to crates.io, creates the release git tags, and creates the public `zebrad` GitHub Release.
 
 The `zebrad` GitHub Release triggers the downstream release workflows that build and publish signed Docker images, attach signed, checksummed standalone `zebrad` binaries (Linux `x86_64` and `aarch64`) to the GitHub Release, and deploy long-lived GCP nodes.
-Until release-preparation data is automated, any required checkpoint, end-of-support height, README, or operational release-note changes should land on `main` before the generated Release PR is merged.
+Changelogs are authored in source PRs rather than generated by release-plz. Final release headings and any required checkpoint, end-of-support height, README, or operational release-note changes must land on `main` before maintainers approve the generated Release PR.
 
 release-plz embeds the release checklist in the generated Release PR body using the `pr_body` configured in `.release-plz.toml`.
 GitHub pull request templates are only used when a maintainer manually opens a pull request in the GitHub UI.