mariadb-operator-release-notes

mariadb-operator 发布说明

为新版本生成两份发布文档，并通过 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_TOKEN="$GITHUB_MARIADB_OPERATOR_TOKEN" gh ...，不要使用当前环境中的 gh auth 会话），然后使用通用的 mcp__github__* 工具，最后使用普通的 gh auth。

---

步骤 0 — 收集输入

首选输入：发布 PR。 用户会提供发布 PR（标题为 Release <version>，源分支为 release-<version>，目标分支为 main）。其正文是确定顺序和范围的依据：它会列出本次发布中的所有 PR，通常按合并目标分组（“merged into main”、“merged into this branch”）。

使用 GitHub MCP 服务获取该 PR：

• 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 正文，查看 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

此处的任何变更（Agent/init 行为、渲染配置、环境变量、备份/恢复 CLI、默认镜像）都意味着必须将data-plane更新到新版本。还应检查此次发布是否更新了默认的 MariaDB 镜像（Makefile 中的 RELATED_IMAGE_MARIADB_VERSION）— 这也应写入发布说明。

第 2 步 — 分组

将 PR 映射到逻辑分组中，并按相关性排序（面向用户的重大功能优先）。本项目通常采用以下章节顺序——只使用有内容的章节：

• MariaDB <X.Y> 支持 — 新的默认服务端版本、兼容性变更
• 复制拓扑 — 高可用编排变更（切换、故障转移、半同步、GTID 处理、read_only）
• Galera 改进 — 集群变更
• 备份 — 备份／恢复／PITR 功能
• 错误修复 — 用户可见的修复
• 改进 — 可观测性、文档、CI、工具链

每项用一个项目符号说明具体变更及其重要性，并附上 PR 链接： - 修复了可能导致 Y 的 X（[#1234](https://github.com/mariadb-operator/mariadb-operator/pull/1234)）。 说明变更即可：写一到两句话，不要进行取证分析。

按读者的实际体验分组，而不是按 PR 归属分组：一个 PR 可以在两个章节中分别列出项目（例如，Galera 修复和通用备份参数修复），章节中不得收录与主题无关的项目。

在行文中致谢社区贡献者，遵循之前版本标题中的惯例：

• 由贡献者主导的主要功能 → 在对应章节末尾添加一行：感谢 @handle 全程推动此功能落地！
• 其他贡献 → 在项目的 PR 链接后追加：（[#1234](...)，感谢 @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/ 链接中则不补零。两种格式须与上一版标题保持一致。
• 标题中的所有链接都必须是绝对链接（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 步的数据平面检查发现变更，须包含数据平面步骤，并在同一句中说明原因，指出具体的数据平面变更（初始化容器配置渲染、Agent 行为）。除此之外，沿用上一版指南的原文。
• 结尾须添加 > [!NOTE]，说明用户需要了解但无需采取行动的版本特定行为变更——例如默认值变更（如默认 mariadb 镜像），或更新后协调完成的服务端状态与之前不同。仅在确有迁移风险（破坏性变更、机制已弃用）时使用 > [!CAUTION]。
• 命令中的 Helm chart 版本不补零（--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，目标分支为 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，应将其放在标题的分组部分中；不要在标题中添加第三个变更日志部分。
• 可能存在回移发布（例如 release-26.6.1）。“从早于 <major.minor>.x 的版本更新到 <version>”这一行必须与所记录发布的实际次版本系列一致。
• 绝不要编造里程碑编号。 Star、PR、采用者数量：只能使用用户提供的数据，或在发布时可通过仓库／软件包页面核实的数据。
• 核实有关上游 MariaDB 的说法（LTS 状态、EOL 日期、功能可用性）是否有权威来源支持，再将其写入发布说明 — 这是项目对外公开的表述。