release-please
基于 Conventional Commits 维护 Release PR、版本与 changelog 的工具；GitHub Action 是其集成方式。
[!info] related notes
- 自动版本实践: release-please 自动版本管理
- 前置规范: Conventional Commits
release-please
Release Please 是 Google 开发的一个 “基于 Git 提交信息（Commit Messages）自动化发布流程” 的工具。用于摆脱手动修改版本号、手动写 Changelog 的痛苦。
核心工具是 googleapis/release-please，googleapis/release-please-action 是在 GitHub Actions 中调用它的集成。它主要维护版本文件、changelog、Release PR 与 GitHub Release；构建、上传包和部署需要单独配置，不会因为提交格式正确就自动完成。
原理（怎么写提交语句）
Release Please 并不是魔法，它极其依赖 Conventional Commits（约定式提交）。它会像一个阅卷老师一样，逐行阅读你两次发布之间的所有 Commit Message。
以下是常见默认策略，主要用于稳定版本；0.x、预发布、语言策略和显式版本覆盖可能改变结果：
| 提交类型 (Prefix) | 含义 | 版本号影响 (SemVer) | 例子 |
|---|---|---|---|
fix: | 修复 Bug | Patch (0.0.x) | fix: 修复了登录按钮点击无效的问题 |
feat: | 新功能 | Minor (0.x.0) | feat: 增加黑暗模式支持 |
perf: | 性能优化 | Patch (通常) | perf: 优化首页加载速度 |
chore: | 杂务 | 无 (不触发发布) | chore: 更新依赖库 |
feat!:,fix!:,refactor!: | 重大变更 | Major (x.0.0) |
提交不符合可解析格式（如 update code）时，可能无法贡献预期的版本与 changelog。普通 chore: 默认不触发版本，但带 breaking-change 或 Release-As 等显式覆盖的提交不能按这个简表判断。0.x 行为还需核对 bump-minor-pre-major、bump-patch-for-minor-pre-major 等配置。
线性 Git 提交历史（使用 squash-merge）
上游推荐 squash-merge，使主分支上的提交更接近一次完整变更，并便于控制最终 Conventional Commit 消息。这是工具使用建议，不覆盖具体仓库的合并策略；squash 后的 PR 标题或最终提交消息也需要正确格式。git bisect 能定位回归，但不能保证每个历史提交都通过测试。
如果我的 PR 包含多个修复或功能怎么办？
Release Please 允许您使用页脚在单个提交中表示多个更改：
feat: adds v4 UUID to crypto
This adds support for v4 UUIDs to the library.
fix(utils): unicode no longer throws exception
PiperOrigin-RevId: 345559154
BREAKING-CHANGE: encode method no longer throws.
Source-Link: googleapis/googleapis@5e0dcb2
feat(utils): update encode to support unicode
PiperOrigin-RevId: 345559182
Source-Link: googleapis/googleapis@e5eef86上述提交信息将包含：
- **为“向加密添加 v4 UUID”**功能添加条目。
- **添加了“unicode不再抛出异常”**的修复条目，并注明这是一个重大更改。
- **为“更新编码以支持 Unicode”**功能添加条目。
⚠️ **重要提示：**附加消息必须添加到提交的末尾。
如何更改版本号？
当提交到主分支的提交内容中包含Release-As: x.x.x不区分大小写）时，Release Please 将为指定的版本打开一个新的拉取请求。
空提交示例：
git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"提交信息如下：
chore: release 2.0.0
Release-As: 2.0.0如何修改发行说明？
如果您已合并一个拉取请求，并希望修改用于生成该提交发布说明的提交消息，您可以编辑已合并拉取请求的正文，并添加如下部分：
BEGIN_COMMIT_OVERRIDE
feat: add ability to override merged commit message
fix: another message
chore: a third message
END_COMMIT_OVERRIDE下次 Release Please 运行时，它将使用该覆盖部分作为提交消息，而不是合并后的提交消息。
⚠️ **重要提示：**此功能不适用于普通合并，因为 release-please 无法确定要将覆盖应用于哪个提交。我们建议改用 squash-merge。
工作流程：它的一生（生命周期）
常见工作流分为维护 Release PR 和创建 Release 两阶段。以下以发布分支 main、Node 项目为例，实际分支、tag、PR 名称和版本文件由配置决定。
阶段一：维护 Release PR
这是你日常开发时发生的事情。
- 你在
main分支合并了一个代码，比如feat: 添加搜索功能。 - Release Please 运行，发现这是一个新功能。
- 它通常先创建或更新该发布分支和组件的 Release PR，而不是立刻发布。
- 如果没有： 它会创建一个新的 PR。
- 如果有： 它会更新这个 PR。
- 在这个 PR 里，它做了两件事：
- 修改
CHANGELOG.md：把你的feat: 添加搜索功能写入待发布日志。 - 修改
package.json：把版本号从1.0.0预改为1.1.0。
此时，这个 PR 就是一个“待办的发布单”。 你可以继续提交代码，Release Please 会不断更新这个 PR，把新的改动加进去。
阶段二：创建 Release
当你觉得“功能攒够了，该发布了”：
- 有合并权限的维护者按仓库流程合并 Release PR。
- Release Please 再次被触发。
- 它发现是它自己创建的 PR 被合并了。
- 它执行最终操作：
- 在 GitHub 上创建一个 Tag (例如
v1.1.0)。 - 在 GitHub 上创建一个 Release，把 Changelog 贴进去。
- 在 GitHub 上创建一个 Tag (例如
配置
github Action 中使用
Token
默认可使用 GITHUB_TOKEN。上游给出的工作流权限如下；PAT 或 GitHub App token 的权限需要在对应凭据中配置，不能靠 YAML 扩权：
permissions:
contents: write
issues: write
pull-requests: writealso need to set “Allow GitHub Actions to create and approve pull requests” under repository Settings > Actions > General.
Release Types Supported
这个参数告诉 Release Please 怎么处理版本文件。
node: 它会去找package.json。simple: 使用通用策略维护version.txt与 changelog，不绑定特定语言的包管理文件。 选择对应的配置才能够自动修改 包的版本管理，比如自动修改 package.json 中的版本号
相关笔记
- github-actions-manual-trigger：如何手动触发 GitHub Actions workflow，为已有 release 补充二进制文件
参考
google-release-please github 文档 google-release-please-action github 文档
Digital Biome