mariadb-operator-release-notes

mariadb-operator リリースノート

新しいバージョン向けに次の2つのリリースドキュメントを作成し、リリースブランチに対するPRとして提出します。

• docs/releases/RELEASE_<version>_HEADER.md.gotmpl — リリースノートのヘッダー
• docs/releases/UPGRADE_<version>.md — アップグレードガイド

リリースノートの生成方法

.github/workflows/release.yml はリリースタグで goreleaser を実行します。docs/releases/RELEASE_${VERSION}_HEADER.md.gotmpl（見つからない場合は汎用の RELEASE_HEADER.md.gotmpl）を検索し、レンダリングした内容を自動生成される「What's Changed」の変更履歴の先頭に追加します。その結果、次の点に注意が必要です。

• ファイル名はタグと完全に一致させる必要があります。タグが 26.10.0 の場合、ファイル名は RELEASE_26.10.0_HEADER.md.gotmpl です。
• ヘッダーはテンプレートです。プロジェクト名をハードコードせず、{{ .ProjectName }} を使用してください。
• ヘッダーにコミット／PRの変更履歴全体を記載しないでください。goreleaser が完全な変更履歴を追加します。ヘッダーには、セクションごとにまとめた主な変更点と、各項目へのPRリンクを記載します。
• この挙動を前提とする前に、.github/workflows/release.yml でタグとファイルの正確な対応関係を確認してください。

GitHub 認証情報

以下のステップでのすべての GitHub 呼び出しでは、プロジェクト専用の GitHub MCP ツール （mcp__github-mariadb-operator__*）を使用します。このサーバーに接続されていない場合は、次の順にフォールバックします。プロジェクトのトークンを使った gh CLI（環境内の gh auth セッションではなく、GH_TOKEN="$GITHUB_MARIADB_OPERATOR_TOKEN" gh ... を使用）、汎用の mcp__github__* ツール、その後に通常の gh auth。

---

ステップ 0 — 入力情報を集める

推奨する入力：リリースPR。 ユーザーからリリースPR（タイトルが Release <version>、ヘッドブランチが release-<version>、ベースブランチが main）を受け取ります。その本文を、対象範囲と順序の根拠とします。本文にはリリースに含まれるすべてのPRが記載され、通常はマージ先（「merged into main」「merged into this branch」）ごとにまとめられています。

GitHub MCP サーバーを使って取得します。

• mcp__github-mariadb-operator__pull_request_read(method="get", owner="mariadb-operator", repo="mariadb-operator", pullNumber=<release-pr>) → タイトル、本文、headRefName、baseRefName

本文から、リリースに含まれるPRリンクの一覧を解析します。リリースノートを作成する時点では、一覧に記載されたすべてのPRがマージ済みであることが想定されます。以前の会話で記録されたステータスを信頼せず、リリースPRの本文で現在の状態を再確認してください。

代替手順：リリースPRが提供されていない場合。 リリースする新しいバージョン（例：26.10.0）をユーザーに尋ねます。その後、Git の履歴から変更内容を推定します。

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

マージコミットをPR番号に対応付けます（コミットの件名と、コミット本文にある pull/ の参照を確認します）。また、作業を進める前に、リモートに release-<version> ブランチが存在することを確認してください。履歴が曖昧な場合（スカッシュマージやリベースなど）は、その旨を伝え、PRに対応付けられなかったコミットを一覧にします。

ステップ 1 — 対象のPRを読む

リリースに含まれるPRごとに、次を取得します。

• mcp__github-mariadb-operator__pull_request_read(method="get", owner="mariadb-operator", repo="mariadb-operator", pullNumber=<n>) → タイトル、本文、作成者、状態

各PRを機能（新しい機能、新しい仕様フィールド）、バグ修正、改善（パフォーマンス、ツール、CI）、ドキュメント、またはツールチェーン（依存関係／ツールの更新）に分類します。

作成者（user.login）と、head.repo がフォークかどうかを記録します。メンテナーではない人がフォークから作成したPRはコミュニティからの貢献であり、ノートでクレジットを記載します（ステップ2）。また、PR本文に記載された共同作成者も確認し、同様にクレジットを記載します。

次に、アップグレードガイドの内容を決めるデータプレーンへの影響を判定します。

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

ここでの変更（エージェント／初期化の動作、レンダリングされた設定、環境変数、バックアップ／復元CLI、デフォルトイメージ）は、データプレーンを新しいバージョンに更新する必要があることを意味します。また、このリリースでデフォルトの MariaDB イメージが更新されるか（Makefile の RELATED_IMAGE_MARIADB_VERSION）も確認してください。該当する場合はノートに記載します。

ステップ 2 — セクションに分類する

PR を関連性の高い順（ユーザー向けの大きな機能を先頭）に、論理的なグループへ分類します。このプロジェクトで一般的なセクション構成は次のとおりです。内容があるものだけを使ってください。

• MariaDB <X.Y> のサポート — 新しいデフォルトのサーバーバージョン、互換性の変更
• レプリケーションのトポロジー — HA オーケストレーションの変更（スイッチオーバー、フェイルオーバー、準同期、GTID の処理、read_only）
• Galera の改善 — クラスタリングの変更
• バックアップ — バックアップ／リストア／PITR の機能
• バグ修正 — ユーザーに影響する修正
• 改善 — 可観測性、ドキュメント、CI、ツールチェーン

各項目は、具体的な変更内容、重要な理由、PR へのリンクを記載した箇条書き 1 つにします。 - Fixed X that could Y ([#1234](https://github.com/mariadb-operator/mariadb-operator/pull/1234))。 変更内容の説明にとどめ、1〜2 文にしてください。調査の経緯は含めません。

PR の内容ではなく、読者が経験することに基づいて分類してください。1 つの PR が 2 つのセクションに箇条書きを追加してもかまいません（例：Galera の修正と、汎用的なバックアップ引数の修正）。また、セクションにはそのトピックに属さない項目を含めないでください。

これまでのリリースヘッダーの慣例に従い、コミュニティからの貢献にクレジットを付けます。

• 貢献者が主導した主要機能 → セクション末尾に次の行を追加します：Kudos to @handle for driving this feature end to end!
• その他すべて → PR リンクの後ろに追加します：([#1234](...), thanks @handle!)
• PR の作成者と、PR でクレジットされている共同作成者にクレジットを付けます。この方法でメンテナーにクレジットを付けてはいけません。ハンドルは user.login の値をそのまま使います。

ステップ 3 — リリースノートのヘッダーを書く

最新バージョンのヘッダーをテンプレートとして、docs/releases/RELEASE_<version>_HEADER.md.gotmpl を作成します（最初に docs/releases/RELEASE_<previous>_HEADER.md.gotmpl を読んでください）。構成：

**`{{ .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>

書式ルール（レビューでの修正事項です。あらかじめ適用してください）：

• バージョン表記はコンテキストによって異なります：タイトルのリンクテキストはゼロ埋めします（26.10.0 の場合は 26.10）。releases/tag/ のリンクではゼロ埋めしません。両方の表記を前回のリリースヘッダーに合わせてください。
• ヘッダー内のすべてのリンクは絶対 URL にしてください（https://github.com/mariadb-operator/mariadb-operator/blob/main/docs/<doc>.md）。ヘッダーは GitHub のリリースページに表示されます。./replication.md のような相対リンクはリリース URL を基準に解決され、404 になります。アンカー（#section）がリンク先のドキュメントに存在することを確認してください。見出しを grep してください。
• 新しい仕様フィールドを記載する場合は、記述前にリリースブランチの api/v1alpha1/ で正確なフィールド名と列挙値を確認してください。リリースノートに誤ったフィールド名が記載されると、すべての読者に届いてしまいます。
• 主要機能には、前回のヘッダーのスタイルに合わせた YAML の例を添えてもかまいません。

ステップ 4 — アップグレードガイドを書く

前回のガイドの構成をコピーして、docs/releases/UPGRADE_<version>.md を作成します。

# <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)

• ステップ 1 のデータプレーン確認で変更が見つかった場合は、データプレーンの手順を含め、同じ文の中でその理由を具体的なデータプレーンの変更（init コンテナーの設定レンダリング、エージェントの動作など）を挙げて説明してください。それ以外の部分は前回のガイドの文言をそのまま維持してください。
• ユーザーが知っておく必要はあるものの対応は不要な、リリース固有の動作変更について、末尾に > [!NOTE] を付けて説明してください。対象には、デフォルトの変更（例：デフォルトの mariadb イメージ）や、更新後に異なる状態へ調整されるサーバー状態が含まれます。> [!CAUTION] は、実際に移行上の危険がある場合（破壊的変更、非推奨の仕組み）に限って使ってください。
• コマンド内の Helm チャートのバージョンはゼロ埋めしません（--version 26.10.0）。

ステップ 5 — プッシュ前に確認する

# 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

最後のリストをリリース PR のリストと照合してください。すべての PR が含まれ、それ以外は何も含まれていないことを確認します。その後、両方のファイルを最初から最後まで読み直し、バージョン文字列がコンテキストに応じた正しい形式であること、すべての @handle が PR の作成者と一致すること、すべてのフィールド名が api/v1alpha1/ と一致すること、アップグレードガイドが前回のリリースのユーザーに適用できることを確認してください。

ステップ 6 — PR として提出する

• release-<version> からブランチ feature-release-notes-<version> を作成します。

• 両方のファイルをコミットします。コミットメッセージは「Add release notes and upgrade guide for 」です。

• ブランチをプッシュし（git push origin feature-release-notes-<version>）、GitHub MCP サーバーを使って PR を作成します。PR のターゲットは release-<version> にします。

  • 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=...)

• マージする前に人によるレビューを待ちます。リリースドキュメントを自分でマージしてはいけません。

注意事項

• 生成された変更履歴には、すべての PR がすでに記載されています。 ユーザーが PR への言及を希望する場合は、ヘッダー内のグループ化されたセクションに含めます。ヘッダーに 3 つ目の変更履歴セクションを追加してはいけません。
• バックポートリリースもあります（例：release-26.6.1）。「<major.minor>.x より前のバージョンから <version> への更新」という行は、ドキュメントを作成するリリースの実際のマイナーシリーズと一致させる必要があります。
• マイルストーン番号を捏造してはいけません。 スター数、プル数、導入者数は、ユーザーから提供された情報、またはリリース時点でリポジトリやパッケージのページで検証できる情報に限ります。
• MariaDB 上流に関する主張（LTS のステータス、EOL 日、機能の提供状況など）は、記載する前に信頼できる情報源で確認します。リリースノートはプロジェクトを代表する公開情報です。