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.

Step 3 — Write the release notes header

Write docs/releases/RELEASE_<version>_HEADER.md.gotmpl, following the most recent version's header as the template (read docs/releases/RELEASE_<previous>_HEADER.md.gotmpl first). Structure:

**`{{ .ProjectName }}` [<zero-padded short version>](https://github.com/mariadb-operator/mariadb-operator/releases/tag/<version>) is here!** 🦭

<enthusiastic open-source intro; highlight any milestones the user provides, e.g. star count, Docker pulls —
never invent numbers>
<community thank-you paragraph, pointing at the inline credits in the sections below>

If you're upgrading from previous versions, __do not miss the [UPGRADE GUIDE](https://github.com/mariadb-operator/mariadb-operator/blob/main/docs/releases/UPGRADE_<version>.md)__ for a smooth transition.

## <feature section>
...

## Bugfixes
...

## Improvements
...

---

## Community
<same adopters/stars paragraph as previous releases>

## Enterprise
<same Enterprise Operator paragraph as previous releases>

Formatting rules (these are the review corrections — apply them up front):

• Version forms differ by context: the title link text is zero-padded (26.10 for 26.10.0), the releases/tag/ link is not. Keep the two forms consistent with the previous release's header.
• Every link in the header must be absolute (https://github.com/mariadb-operator/mariadb-operator/blob/main/docs/<doc>.md). The header is rendered on the GitHub releases page, where relative links such as ./replication.md resolve against the release URL and 404. Anchors (#section) must exist in the target doc — grep its headings.
• New spec fields: verify the exact field name and enum values against api/v1alpha1/ on the release branch before writing them — wrong field names in release notes ship to every reader.
• A YAML example may accompany a headline feature, mirroring the style of the previous header.

Step 4 — Write the upgrade guide

Write docs/releases/UPGRADE_<version>.md, copying the previous guide's structure:

# <zero-padded short version> update guide

This guide illustrates, step by step, how to update to `<version>` from previous versions. This guide only
applies if you are updating from a version prior to `<zero-padded>x`, otherwise you may upgrade directly
(see [Helm](../helm.md#updates))

> [!TIP]  (OCI-based installation — same block as previous guides)
> [!CAUTION]  (mariadb-operator-crds in-place upgrade — same block as previous guides)

- The [data-plane](../data_plane.md) must be updated ... `updateStrategy.autoUpdateDataPlane=true` diff block
- Upgrade `mariadb-operator-crds` then `mariadb-operator` helm chart to `<version>` (bash blocks)
- Consider reverting `updateStrategy.autoUpdateDataPlane` back to `false` (diff block)

• Include the data-plane step when Step 1's data-plane check found changes, and state why in the same sentence, naming the concrete data-plane change (init-container config rendering, agent behavior). Keep the previous guide's exact wording otherwise.
• Close with a > [!NOTE] per release-specific behavior change users must know about but need not act on — a changed default (e.g. the default mariadb image), or reconciled server state that differs after the update. Use > [!CAUTION] only for actual migration hazards (breaking change, deprecated mechanism).
• Helm chart versions in commands are not padded (--version 26.10.0).

Step 5 — Verify before pushing

# filenames match the tag exactly (release.yml lookup)
ls docs/releases/RELEASE_<version>_HEADER.md.gotmpl docs/releases/UPGRADE_<version>.md

# template variables and links are sane
grep -n "{{ .ProjectName }}" docs/releases/RELEASE_<version>_HEADER.md.gotmpl
grep -n "UPGRADE_<version>.md" docs/releases/RELEASE_<version>_HEADER.md.gotmpl
# no relative doc links leaked into the header (must be empty)
grep -n '](\.\?\./' docs/releases/RELEASE_<version>_HEADER.md.gotmpl
# every PR of the release is cited exactly where expected
grep -o 'pull/[0-9]*' docs/releases/RELEASE_<version>_HEADER.md.gotmpl | sort -u

Compare that last list against the release PR's list: every PR must appear, and nothing else may. Then re-read both files end to end: every version string in the right form for its context, every @handle matching the PR author, every field name matching api/v1alpha1/, and the upgrade guide applicable to users of the previous release.

Step 6 — Deliver as a PR

• Branch feature-release-notes-<version> from release-<version>.

• Commit both files: "Add release notes and upgrade guide for <version>".

• Push the branch (git push origin feature-release-notes-<version>), then open the PR targeting release-<version> with the GitHub MCP server:

  • mcp__github-mariadb-operator__create_pull_request(owner="mariadb-operator", repo="mariadb-operator", title="Add release notes and upgrade guide for <version>", head="feature-release-notes-<version>", base="release-<version>", body=...)

• Wait for human review before merging — never self-merge release docs.

Gotchas

• The generated changelog already lists every PR. If the user wants a PR mentioned, it belongs in the header's grouped sections; do not add a third changelog section to the header.
• Backport releases exist (e.g. release-26.6.1). The "update to <version> from a version prior to <major.minor>.x" line must match the actual minor series of the release being documented.
• Never invent milestone numbers. Stars, pulls, adopters: only what the user provided or that is verifiable on the repository/package pages at release time.
• Verify claims about upstream MariaDB (LTS status, EOL dates, feature availability) against an authoritative source before writing them — the release notes are the project's public voice.