Bitcoin Core 发布说明模板解析：从 release-notes-empty-template.md 理解版本发布文档规范

本文以 release-notes-empty-template.md 为骨架，逐节拆解 Bitcoin Core 官方发布说明（Release Notes）的空白模板：各章节的用途、占位符的含义、升级与兼容性说明的固定表述，以及漏洞披露的既定流程。结合仓库内的发布流程文档（release-process.md）、开发者规范（developer-notes.md）和历史版本的实际成品文件，你可以完整掌握“从空模板到最终发布说明”的写作规范与协作机制，学会按项目惯例为 PR 撰写发布说明片段。

一、模板的定位：发布周期中的“起点文件”

该文件开头即声明了自己的性质：

The release notes draft is a temporary file that can be added to by anyone. See developer-notes.md#release-notes for the process.

也就是说，它不是一个只读的样板，而是发布说明草稿的初始骨架：任何贡献者都可以在它的基础上追加内容。它与发布流程的衔接点在 release-process.md 中写得很明确：

• 每次主版本分支切出（branch-off）之后，维护者会执行 cp doc/release-notes-empty-template.md doc/release-notes.md，即用本模板清空并重置工作分支上的 doc/release-notes.md，然后在其上进行协作编辑（详见 release-process.md 的 “After branch-off” 一节）；
• 草稿在分支上编辑期间，版本号为空的状态会通过协作 wiki 供公告引用，直到 -final 版本定稿；
• 正式发布后，成品会被归档到 doc/release-notes/release-notes-${VERSION}.md（例如 release-notes-31.1.md），而 master 与发布分支上的旧笔记则继续以本模板为基础清空复用。

因此，本模板实际上定义的是：每个主版本发布说明必须包含哪些章节、以什么顺序组织、哪些固定表述不可随意改动。

二、开篇样板：版本横幅与固定声明

模板第 5～24 行是发布说明的“横幅区”，包含五个要素，成品文件中它们会按相同顺序出现：

1. 标题与版本占位符：*version* Release Notes Draft，其中 *version* 是待替换的占位符（如 31.1）。标题下的 =============================== 分隔线沿用了纯 Markdown 的 Setext 风格标题，与仓库内其他 .md 文档保持一致。
2. 下载入口声明：Bitcoin Core version *version* is now available from: <https://bitcoincore.org/bin/bitcoin-core-*version*/>，指明该版本二进制分发目录的 URL 模式（版本号在目录名中重复出现一次）。
3. 变更总览：“This release includes new features, various bug fixes and performance improvements, as well as updated translations.” 这是一句固定套话，用于概括本次发布的三类内容。
4. 问题反馈渠道：指向 GitHub issue tracker；安全与更新公告订阅：指向官方公告邮件列表。模板要求这两条渠道信息在每个版本中保持出现。
5. EOL（End of Life）声明：

With the release of this new major version, versions version minus 3 and older are at "End of Life" and will no longer receive updates.

这条声明确立了项目**“维护最近 3 个主版本系列”**的策略：发布新版后，三个主版本之前的系列停止更新。撰写时把 *version minus 3* 替换为实际数值即可。

三、安全政策条款：两阶段漏洞披露

模板第 26～30 行是安全相关的关键段落：

In accordance with the security policy, we will in two weeks disclose:

• Medium and high severity vulnerabilities fixed in version minus 2. There are N of these.
• Low severity vulnerabilities fixed in version. There are M of these.

这里体现了两阶段披露机制：

• 中高危漏洞：在上一个主版本（*version minus 2*）中修复，但在该版本发布时不公开细节，而是在再下一个主版本发布两周后才披露，以给部署升级留出缓冲；
• 低危漏洞：在当前版本（*version*）中修复并披露，同样适用两周窗口；
• N、M 为占位计数，撰写发布说明时必须替换为实际数量。

撰写者需要注意：如果当前发布周期内没有对应级别的漏洞，该段落需按实际情况调整表述，而不是照抄数字。

四、How to Upgrade：跨平台升级步骤

模板 “How to Upgrade” 章节给出了一份刻意保持通用、可复用的升级指引：

• 先关闭旧版本，并等待其完全退出（模板特别注明“可能需要几分钟”——对应大型数据目录的关闭落盘场景）；
• 然后按平台操作：Windows 运行安装程序；macOS 直接覆盖 /Applications/Bitcoin-Qt；Linux 覆盖 bitcoind/bitcoin-qt 二进制；
• 明确说明从已 EOL 的版本直接升级是可行的，但若数据目录需要迁移（migration）可能耗时较长，且旧钱包格式大体上仍受支持。

这段文字是“用户必读”部分，因此在每个版本的成品发布说明中几乎原样保留（对比 release-notes-31.1.md 开头可验证这一点）。撰写新发布说明时，应只在其确有变化的情况下修改（例如数据库迁移机制变化），避免破坏用户习惯。

五、Compatibility：受支持平台的固定表述

模板 “Compatibility” 章节声明当前的官方支持矩阵：

Linux Kernel 3.17, macOS 14, and Windows 10 (version 1903)

并附两条限定：其他类 Unix 系统“可以工作但测试较少”；不建议在不受支持的系统上使用。撰写时的任务是核对这三个基线（Linux 内核版本、macOS 主版本、Windows 版本）是否随构建矩阵变化而更新，其余表述保持不变。

六、Notable changes：面向用户的变更清单

这是模板的核心骨架，预置了六个小节，按“变更类型”而非“代码模块”组织，目的是让最终用户快速定位与自己相关的改动：

小节	内容	撰写要求
P2P and network changes	网络协议、连接、隐私相关变更	面向节点运营者描述行为变化
Updated RPCs	既有 RPC 的参数/返回值变化	钱包相关 RPC 的变化不写在这里（见下文交叉引用）
New RPCs	新增 RPC	列出方法与用途
Build System	构建系统变化	CMake 选项、依赖变化等
Updated settings	既有配置项变化	GUI/钱包相关设置移至对应小节
New settings	新增配置项	给出选项名与含义
Tools and Utilities	bitcoin-cli、bitcoin-tx 等工具变化	—
Wallet	钱包行为、迁移、RPC 变化	—
GUI changes	图形界面变化	—

模板在两处留了交叉引用锚点，这是写作规范的一部分：

• “Changes to wallet related RPCs can be found in the Wallet section below.”
• “Changes to GUI or wallet related settings can be found in the GUI or Wallet section below.”

即：RPC 章节只写非钱包 RPC，设置章节只写非 GUI/钱包设置，避免同一变更在多处重复。撰写 PR 发布说明时应据此判断条目归属。

七、Low-level changes：面向开发者的变更清单

“Low-level changes” 面向二次开发者而非终端用户，模板预置：

• RPC：内部 RPC 机制、错误行为、序列化层面的变化；
• Tests：测试框架、测试工具的行为变化。

随后是 *version* change log 章节，用于容纳完整变更清单（历史上该部分由合并的 PR 级笔记按模块归并而来），以及 Credits 章节的固定收尾：

Thanks to everyone who directly contributed to this release:

As well as to everyone that helped with translations on Transifex.

维护者会用 git log --format='- %aN' v<旧版本>..v<新版本> | grep -v 'merge-script' | sort -fiu 生成作者列表填入（命令见 release-process.md），翻译贡献则统一致谢 Transifex 平台上的译者。

八、PR 级发布说明：模板的上游内容来源

模板只是“终点容器”，内容其实来自每个 PR 各自携带的笔记文件。developer-notes.md 的 “Release notes” 一节规定了上游规范：

• 需要写发布说明的 PR 有四类：引入显著新功能、修复重要缺陷、改变 API 或配置模型、以及其他任何用户可见的变更；
• 每个 PR 把笔记写入独立的 doc/release-notes-<PR number>.md 文件，以避免多个 PR 修改同一文件时产生冲突；
• 发布前，所有 release-notes* 文件会被合并进单一的 release-notes-<version>.md。

仓库中现存大量这样的 PR 级文件，例如：

• release-notes-21283.md：以 “Updated RPCs” 为标题，说明 estimatesmartfee 新增 mempool 费率估计器、fee_rate_estimator 可选值（"none" / "block_policy" / "mempool_policy"）及数据文件路径迁移；
• release-notes-35696.md：以 “### P2P and Network Changes” 为标题，说明 I2P 旧 ElGamal（type 0）会话加密的日落计划及对低版本节点的隔离影响；
• release-notes-35319.md：说明 -privatebroadcast=1 下 v2→v1 协议回退连接可能绕过 Tor 代理、泄露源 IP 的修复，并列出触发该问题的四个前提条件。

这些文件的标题层级（###）与模板的小节（##/- 分隔线风格）并不完全一致，正说明它们是“碎片”，需要在合并进版本级笔记时按模板骨架重新归位——模板实际上同时定义了最终成品的目录结构标准。

九、从模板到成品：以 v31.1 为例的对照

对照成品 release-notes-31.1.md 与模板，可以看到填充后的完整形态：

1. 横幅区逐字对应模板：v31.1 Release Notes 标题、下载目录、变更总览句、issue 与公告列表渠道；
2. “How to Upgrade” 与 “Compatibility” 两节与模板文字基本一致，验证了第四、五节所述的“固定表述”惯例；
3. “Notable changes” 下按模块给出条目（PrivateBroadcast、Validation、Leveldb、P2P、Wallet、Musig、Build、Test、Fuzz、Util、Docs、CI、Misc），每条以 PR 编号开头（如 #35410 net: use the proxy if overriden when doing v2->v1 reconnections）；
4. 结尾是 Credits 作者列表 + Transifex 译者致谢，与模板收尾一致。

注意成品中没有出现模板里的“两阶段漏洞披露”段落——这说明安全条款是条件性段落，仅在存在需披露漏洞时填充。

另外，模板中的 *version* 占位符与仓库根 CMakeLists.txt 中的版本变量一一对应：CLIENT_VERSION_MAJOR 31、CLIENT_VERSION_MINOR 99、CLIENT_VERSION_BUILD 0、CLIENT_VERSION_RC 0、CLIENT_VERSION_IS_RELEASE "false"。MINOR=99 且 IS_RELEASE=false 的组合表明当前分支处于发布分支切出后的开发期（主版本 31 分支已切出，master 进入 31.99 开发态）——这正是模板被重置为新草稿、开始填充下一个版本内容的阶段。发布流程要求在正式版本前把 CLIENT_VERSION_RC 复位为 0、CLIENT_VERSION_IS_RELEASE 置为 true（见 release-process.md）。

十、撰写检查清单

按本模板撰写发布说明时，可对照以下清单逐项确认：

• 所有 *version*、*version minus 2*、*version minus 3*、N、M 占位符均已替换为实际值；
• 下载 URL 目录模式 bitcoin-core-*version*/ 与版本号一致；
• EOL 声明中的旧版本数值计算正确（当前主版本减 3）；
• 两阶段漏洞披露段落：有则填数量，无则按情况调整，不保留占位数字；
• 钱包相关 RPC 变更只出现在 Wallet 小节、GUI/钱包设置只出现在 GUI/Wallet 小节，遵守模板中的交叉引用约定；
• 每条用户可见变更都能溯源到对应 PR 编号；
• 完成后由维护者合并 PR 级 release-notes-<PR number>.md 文件，归档至 doc/release-notes/ 并在分支上清空回模板。

掌握这套模板与流程后，无论是为 PR 撰写 doc/release-notes-<PR number>.md 片段，还是审阅最终版本笔记，都能以 release-notes-empty-template.md 的章节骨架为锚，保持与 developer-notes.md 规范及 release-process.md 流程的一致性。