Mariadb Operator Release Notes

mariadb-operator Release Notes

Produce the two release documentation artifacts for a new version and deliver them as a PR against the release branch:

• docs/releases/RELEASE_<version>_HEADER.md.gotmpl — the release notes header
• docs/releases/UPGRADE_<version>.md — the upgrade guide

How release notes are built

.github/workflows/release.yml runs goreleaser on the release tag. It looks for docs/releases/RELEASE_${VERSION}_HEADER.md.gotmpl (falling back to the generic RELEASE_HEADER.md.gotmpl) and prepends its rendered content to the auto-generated "What's Changed" changelog. Consequences:

• The filename must match the tag exactly: tag 26.10.0 → RELEASE_26.10.0_HEADER.md.gotmpl.
• The header is a template: use {{ .ProjectName }} for the project name, never hardcode it.
• Do not write a full commit/PR changelog in the header — goreleaser appends the complete one. The header carries the narrative: highlights grouped into sections, each item linking its PR.
• Verify the exact tag-to-file lookup in .github/workflows/release.yml before relying on it.

GitHub credentials

All GitHub calls in the Step sections below use the project-scoped GitHub MCP tools (mcp__github-mariadb-operator__*). If that server isn't connected, fall back in order: gh CLI with the project token (GH_TOKEN="$GITHUB_MARIADB_OPERATOR_TOKEN" gh ..., not the ambient gh auth session), then the generic mcp__github__* tools, then plain gh auth.

Step 0 — Gather the input

Preferred input: the release PR. The user provides the release PR (titled Release <version>, head branch release-<version>, base main). Its body is the ordering and scope authority: it lists every PR in the release, typically grouped by where it merged ("merged into main", "merged into this branch").

Fetch it with the GitHub MCP server:

• mcp__github-mariadb-operator__pull_request_read(method="get", owner="mariadb-operator", repo="mariadb-operator", pullNumber=<release-pr>) → title, body, headRefName, baseRefName

Parse the body into the list of PR links included in the release. By the time release notes are written, every listed PR is expected to be merged — re-check the release PR body for the current state rather than trusting a status that was recorded earlier in the conversation.

Fallback: no release PR provided. Ask the user for the new version to release (e.g. 26.10.0). Then infer the change set from git history:

git fetch --tags origin main release-<version>
LAST_TAG=$(git describe --tags --abbrev=0 release-<version> 2>/dev/null || git describe --tags --abbrev=0 origin/main)
git log --oneline ${LAST_TAG}..origin/release-<version>                 # what changed
git log --merges --pretty='%h %s' ${LAST_TAG}..origin/release-<version> # merge commits → PRs

Map merge commits back to PR numbers (commit subjects and the pull/ refs in commit bodies), and confirm the release-<version> branch exists on the remote before proceeding. If the history is ambiguous (squashed merges, rebases), say so and list the commits you could not attribute to a PR.

Step 1 — Read the included PRs

For every PR in the release, fetch:

• mcp__github-mariadb-operator__pull_request_read(method="get", owner="mariadb-operator", repo="mariadb-operator", pullNumber=<n>) → title, body, author, state

Classify each: feature (new capability, new spec field), bugfix, improvement (perf, tooling, CI), docs, or toolchain (dependency/tool bumps).

Record the author (user.login) and whether head.repo is a fork: a PR authored from a fork by someone who is not a maintainer is a community contribution and gets credited in the notes (Step 2). Also read the body for co-authors the PR itself credits — they get credited too.

Then determine the data-plane impact, which decides the upgrade guide content:

git diff --stat ${LAST_TAG}..origin/release-<version> -- \
  cmd/init cmd/agent pkg/controller/replication/config.go pkg/galera/config \
  pkg/environment pkg/builder/container_builder.go pkg/command

Any change here (agent/init behavior, rendered config, env vars, backup/restore CLIs, default images) means the data-plane must be updated to the new version. Also check whether the release bumps the default MariaDB image (RELATED_IMAGE_MARIADB_VERSION in the Makefile) — that belongs in the notes.

Step 2 — Group into sections

Map the PRs into logical groups sorted by relevance (biggest user-facing features first). Typical section lineup for this project — use only the ones that have content:

• MariaDB <X.Y> support — new default server version, compatibility changes
• Replication topologies — HA orchestration changes (switchovers, failovers, semi-sync, GTID handling, read_only)
• Galera improvements — clustering changes
• Backups — backup/restore/PITR features
• Bugfixes — user-visible fixes
• Improvements — observability, docs, CI, toolchain

Every item is one bullet naming the concrete change, why it matters, and a PR link: - Fixed X that could Y ([#1234](https://github.com/mariadb-operator/mariadb-operator/pull/1234)). Stop at the change: one or two sentences, no forensics.

Group by what the reader experiences, not by which PR shipped it: one PR can contribute bullets to two sections (e.g. a Galera fix plus a generic backup-args fix), and a section must not collect items that don't belong to its topic.

Credit community contributions inline, following the convention of previous headers:

• Headline feature driven by a contributor → a closing line in its section: Kudos to @handle for driving this feature end to end!
• Everything else → appended to the bullet's PR link: ([#1234](...), thanks @handle!).
• Credit the PR author and any co-author the PR credits; never credit maintainers this way. Handles are taken verbatim from user.login.