移动 App 更新日志的工程化工作流
每次发版前翻几十条 git log,把 fix(db): filter tombstones in aggregate query 翻译成用户能读懂的商店文案,既容易漏掉关键修复,又容易把重构和内部改动混进去;反过来,直接用自动化工具把提交标题拼成发布说明,C 端用户看到的又是一堆晦涩的工程黑话。
本文整理一套适用于 iOS / Android 双端移动 App(尤其是 Monorepo 与高频 Squash Merge 仓库)的更新日志工程方案。基于截至 2026 年 11 月的 Keep a Changelog 1.1.0 原则、Git Trailer 机制与双商店元数据硬约束,拆解方案选型、两层采集与定稿架构、五个最容易踩中的工程边界坑,以及从草稿到 App Store 和 Google Play 定稿的落地规范。
为什么 Conventional Commits 不能直接当商店更新日志
Git Commit Message 指南 强调提交信息服务于代码审计、二分排查和自动化发布。但提交标题的读者是开发者(英文祈使句、按模块边界划 scope),而 App Store 与 Google Play 更新日志的读者是终端用户(用户的自然语言、讲用户获得了什么价值或不再遇到什么故障)。两者目标天然错位。
目前业界围绕更新日志形成了四种主流模式,选型取决于产品受众、仓库形态与团队规模:
| 方案 | 代表实践 / 工具 | 核心机制 | 优势 | 局限与适用边界 |
|---|---|---|---|---|
| 纯提交标题自动生成 | release-please、semantic-release、git-cliff |
按 Conventional Commits 的 feat/fix 标题自动汇总 |
零人工成本,与语义化版本号强联动 | 适合开源库、SDK、CLI;直接给 C 端 App 用户读会充斥实现细节与噪音 |
| Fragment 文件(Changesets) | @changesets/cli、towncrier、reno |
每个 PR 新增独立描述文件,发版时汇总并消费删除 | 天然适配 PR 粒度与多包 Monorepo,Review 时可直接 diff 文案 | 每个可见 PR 多建一个小文件,对中小团队或单 App 仓库略重 |
| PR 元数据驱动 | GitHub Auto-generated Release Notes、Release Drafter | 靠 PR 标签分类,或从 PR 描述区块提取文案 | 合并前可在网页端直接改文案,无需 amend commit | 强依赖托管平台 API,脱离 Git 历史本身,本地离线发版不自包含 |
| Commit 尾注 + 草稿汇总 + 人工定稿 | GitLab Changelog Entries 思路演进、部分移动端团队 | 开发时在提交正文写尾注,发版时脚本按区间生成草稿,人工润色上架 | 轻量、零外部依赖、Git 历史自包含、对人类和 AI 编码助手都低摩擦 | 需要配套校验脚本处理 Squash Merge、非 App 改动过滤和 CI 兜底 |
需要注意一个小差异:GitLab 原生的 Changelog: added|fixed|changed 尾注只标记分类、正文仍取提交标题本身;面向 C 端移动 App 时,我们借用同样的 Git Trailer 机制,但把值改成一句用户视角的自然语言(Release-Note: ...),从而把开发者提交标题与商店文案彻底解耦。
对于以 C 端 App 为核心交付物、追求轻量工程栈的团队,「Commit 尾注 + 草稿汇总 + 人工定稿」是投入产出比最高的选择:它在改动发生的那一刻由最了解上下文的人写下用户视角的一句话,避免发版时倒推 diff,同时保留了发版前的人工编辑权,保证商店文案质量。
两层架构:开发时采集素材,发版时整理定稿
整套流程把「记录事实」与「面向用户写作」解耦为两层,中间由确定性的本地脚本与 CI 门禁连接:
这种两层分离带来两个直接收益:一是开发期心智负担极低,写一条 Release-Note: 只需几秒;二是脚本产出的只是带短哈希的素材草稿,不会直接推送到商店,哪怕开发期多写或写得略显粗糙,定稿环节仍有完整的兜底空间。
尾注格式与默认分类规则
只有在 App 中能被用户直观看到或感知的变化才写尾注:新功能、交互或行为调整、修复用户可能遇到的故障、可感知的性能提升。重构、测试、文档、CI、无可见变化的依赖升级一律不写。拿不准时用一个判据:用户读到这句话会在意吗? 不会就不写。
尾注放在提交正文末尾,与正文空一行,一条一行:
fix(tags): allow recreating a deleted tag with the same name
Tags are soft-deleted, but UNIQUE(workspace_id, name) still counted
tombstone rows, causing re-creation to fail with a constraint error.
Release-Note: 删除标签后,可以重新创建同名标签了约定保持极简,便于脚本解析和人工记忆:
- 键名固定:
Release-Note: <一句话>,使用团队工作语言(例如简体中文),发版时再统一本地化为其他商店语言,避免每个提交都要维护多语种。 - 自动推导分类:
feat归入「新增」,fix归入「修复」,其余类型(如带来可见提速的perf)归入「改进」。确实与提交类型不符时,允许在正文前加[新增]、[改进]或[修复]显式覆盖。 - 写法约束:建议控制在 60 字以内,不写 PR 号、任务编号、类名或表名。
落地时最容易踩的五个工程坑
把纸面规范跑进真实仓库,往往会撞上五个非常具体的工程细节。每一个都有明确的解法。
Squash Merge 破坏 git interpret-trailers 与子提交分类
很多仓库启用了 GitHub 的 Squash Merge,并将合并提交正文配置为 COMMIT_MESSAGES(把分支上所有提交的标题和正文拼进一个 squash 提交)。这会同时引发两个问题:
- 标准 Trailer 解析失效:git-interpret-trailers 只解析提交信息的最后一个段落。Squash 拼接后,前几个子提交里的
Release-Note:落在了正文中间,会被标准 trailer 解析器静默丢弃。 - 多提交混合类型的分类错配:如果一个
featPR 里顺手夹带了一个fix提交并写了Release-Note:(未加[修复]覆盖),汇总脚本若只看 squash 顶行标题的feat,就会把这条修复错归进「新增」。
可靠的做法是不依赖 git interpret-trailers,而是按 GitHub Squash 正文的 * <type>(<scope>): ... 子提交头把正文拆回各个子提交,再分别提取尾注并按当前子提交的 type 分类:
import re
SUB_COMMIT = re.compile(r"^\*\s+(?P<header>[a-z]+(?:\([^)]*\))?!?: .*)$")
HEADER = re.compile(r"^(?P<type>[a-z]+)(?:\((?P<scope>[^)]*)\))?!?: ")
NOTE = re.compile(r"^Release-Note:[ \t]*(?P<value>.*?)\s*$")
def iter_subcommits(message: str):
"""Yield (header, notes) per sub-commit inside a normal or squashed commit."""
lines = message.splitlines()
if not lines:
return
current_header = lines[0]
current_notes: list[str] = []
saw_subcommit = False
for line in lines[1:]:
sub = SUB_COMMIT.match(line)
if sub:
if saw_subcommit or current_notes:
yield current_header, current_notes
current_header = sub.group("header")
current_notes = []
saw_subcommit = True
continue
note = NOTE.match(line)
if note:
current_notes.append(note.group("value"))
yield current_header, current_notes对于单提交 squash(正文里没有 * ... 列表),iter_subcommits 直接按顶行标题处理;对于多提交 squash,每条 Release-Note: 都能准确回溯到所属子提交的 type 与 scope。
Monorepo 里的范围污染
当移动端 App 与官网(web)、后端接口(api)、构建脚本(scripts)、工作流(workflows)共存于同一个 Monorepo 时,如果不做范围隔离,发版脚本的「未写尾注的 feat/fix 待审列表」会被 fix(web): update landing copy 这类非 App 提交淹没。
更干净的边界是在收集与校验两处同时隔离:
- 汇总脚本侧:定义明确的非 App
scope黑名单(如web、api、contracts、scripts、workflows、ci、docs、infra),跳过这些scope的待补写提示与尾注汇总。 - 提交校验侧:在这些非 App
scope的提交里写了Release-Note:时直接报错拒绝,防止官网或脚本改动意外渗入 App 更新日志。
本地 Hook 与 CI 的职责边界
仅靠本地 commit-msg hook 有两个缺口:一是 --no-verify 会绕过本地检查,二是在网页端编辑 squash 提交信息时不会触发本地钩子。因此 CI 侧必须兜底校验。
但这里有一个常见的反模式:在 CI 里同时运行开源 commitlint 与自研完整提交检查脚本。两套实现对换行、行长、footer 空行或 revert 格式的细微差异,很快就会导致「本地过、CI 挂」或「commitlint 过、自研脚本挂」的分裂体验。
更稳妥的分工是各司其职:
- 提交头与正文规范:继续交给 CI 里现成的
commitlint(读同一份.commitlintrc.json)。 - 尾注格式与范围校验:给自研脚本加一个
--release-notes-only模式,在 CI 的 commitlint 工作流中对 PR 的每个提交只校验Release-Note:行与允许的scope。 - 脚本自测进 CI:把汇总脚本与校验逻辑的单元测试(覆盖 squash 子提交分类、revert 抵消、非 App scope 拒绝、非法分类前缀拦截)接进 CI 的快速脚本测试任务,避免后续改脚本时悄悄回归。
PR 模板与提交尾注的双写误区
如果 PR 模板里放了一个自由填写的 ## Release note 段落,开发者和 AI 助手很容易顺手把更新说明写在 PR 描述里,而忘记写进 commit 正文——结果发版脚本扫描 git log 时什么都捞不到。
解决方案是明确单一事实来源:PR 模板只放一个勾选项(例如「用户可见的改动已在提交正文写 Release-Note:;发版脚本只读提交信息,不读 PR 描述」),并在规范里提醒:在 GitHub 网页端执行 Squash Merge 时,保留子提交正文里的 Release-Note: 行,不要顺手清空。
Revert 抵消与已上架 Tag 基线
发版汇总的起点 FROM 必须是上一个真正在商店上架版本的 tag,而不是中间被打回的审核版本或内部测试包。如果某个功能合并进 main 后又被 git revert 撤回,汇总脚本应扫描 This reverts commit <sha>,将原提交与 revert 提交成对剔除,避免出现「先宣布新增、实际未发布」的乌龙。当传入的 FROM tag 不存在时,脚本应捕获 git 错误并输出一行清晰提示与非零退出码,而不是把堆栈抛给发版人。
从草稿到商店文案:App Store 与 Google Play 落地规范
脚本产出的草稿只是素材。参照 Keep a Changelog 的读者优先原则与两大应用商店的平台规则,整理定稿时重点守住以下约束:
写作准则
- 最重要的放最前:App Store 产品页默认折叠更新日志,只露出前三行左右;第一句必须让用户一眼看出这次值不值得更新。
- 按「新增 / 改进 / 修复」分组:组内按影响面排序,某一组为空则直接省略。
- 写用户所得与故障现象,不写实现:写「导出报表时不再漏掉已归档的条目」,而不是「修复查询条件过滤逻辑」。
- 安全修复不披露细节:涉及安全或隐私漏洞的修复只写「提升了某功能的安全性」,不描述触发路径或可利用细节。
- 拒绝空泛套话:避免通篇只写「修复了一些已知问题并提升了性能」。如果该版本确实只有零碎修复,挑出用户最可能感知的一两条具象写出,再以一句「以及其他稳定性改进」收尾。
- 付费功能明确标注:属于订阅或专业版的新增能力在句末标注(如「(Pro)」),避免免费用户更新后找不到入口产生挫败感。
- 按目标语言重写,不逐字翻译:各语言版本的术语与 App 内本地化文案保持一致,句式按母语习惯自然重组。
双商店字符限制与元数据归档分离
App Store 与 Google Play 对更新日志的硬约束不同,仓库落盘时也要注意工具边界:
| 平台 | 对应字段 | 字符上限与格式 | 特殊约束 | 推荐归档方式 |
|---|---|---|---|---|
| App Store | 版本「新内容」(whatsNew) |
4,000 字符,纯文本不支持 HTML | 首个版本(1.0)不可填写;后续更新版本为必填 | 随版本元数据 JSON 存放(如 store/metadata/version/<ver>/<locale>.json),由 App Store Connect CLI 统一同步 |
| Google Play | 版本说明(What’s new in this release) | 每种语言 500 Unicode 字符(含空格与换行) | 严禁夹带促销广告或引导好评;任一语言超限会导致整次上传被拒 | 单独存放在独立目录(如 store/play/release-notes/<ver>.txt),按 <en-US>...</en-US> 格式分语种保存 |
这里有一个容易忽略的细节:不要把 Google Play 的版本说明塞进 App Store 的 store/metadata/version/ 目录。许多 App Store Connect 自动化上传工具会把整个 metadata 目录作为受控集合进行扫描与同步,混入非标准文件轻则报校验错误,重则影响元数据同步。将两套商店产物物理隔离,既保留了 Play 精简版文案在 Git 中的历史留档,也不干扰 iOS 发布工具链。