substrate/docs/dev/release-notes.md

Release notes

GitHub generates the release notes for each Substrate release from the labels and titles of the merged pull requests. .github/release.yml defines the sections. Pushing a release tag creates a draft release with the generated notes. A maintainer edits the draft and publishes it.

The notes are only as good as the labels. You can fetch the current labels and their descriptions using gh.

gh label list --repo agent-substrate/substrate --limit 200 --json name,description,color

Sections

Each pull request is listed in the first section it matches, in this order:

Section	Labels
⚠️ Breaking Changes	breaking-change
Bug Fixes	kind/bug
Features: Networking and Egress	area/network
Features: Security and Identity	area/security, area/identity
Features: Observability	area/observability
Features: Workers and Actors	area/node, area/gvisor, area/microVM, area/scheduling, area/storage, area/api, area/api-machinery
Features: Install and Operations	area/dev-infra, area/cli, area/reliability, area/demos, area/benchmarking
Documentation	kind/docs
Dependencies	dependencies
Other Changes	everything else

The core feature sections (everything except Install and Operations) run from the most specific area to the broadest. Workers and Actors comes last because area/node and area/api appear on many pull requests as secondary areas. Install and Operations come after all other feature areas. kind/cleanup pull requests are never listed as features; they fall through to Other Changes. Pull requests labeled release-note/none or DO NOT MERGE are left out completely.

Write the title as a release note

The generated notes list each pull request as <title> by @author in <link>. Write the title for someone upgrading Substrate: say what changed for them, not how the code changed.

Instead of	Write
Egresspolicy impl	Enforce EgressPolicy in the egress gateway
multi actor worker support	Run more than one actor on a worker
Fix #1234	Fix the kind install on arm64 hosts

For a breaking change, describe the upgrade step in the pull request's "Breaking change" section. The release manager uses it to write the note.

Cut a release

1. Tag the release commit vX.Y.Z, or vX.Y.Z-rc.N for a release candidate, and push the tag. The release workflow runs hack/release/draft-release.sh, which creates a draft release. The notes cover every change since the previous vX.Y.Z release and end with a list of committers. A release candidate is marked as a prerelease.
2. Edit the draft:
   • Write a summary at the top.
   • Rewrite each breaking change with its upgrade step.
   • Optionally, group the feature sections under one ## Features heading.
   • Remove Other Changes entries users do not need, and move entries that landed in the wrong section.
3. Publish the release.

If the workflow did not run, start it from the Actions tab with the tag as input, or run the script with an authenticated gh that has write access to the repository:

hack/release/draft-release.sh --dry-run v0.3.0   # print the notes only
hack/release/draft-release.sh v0.3.0             # create the draft

The script never modifies a release that already exists.

To preview the notes before tagging, run the dry run with the tag you plan to push. If the tag does not exist yet, the notes run up to your local HEAD, which must already be on a branch in the repository.