目录

移动 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 门禁连接:

flowchart LR Commit["开发提交\n附 Release-Note: 尾注"] --> LocalHook["本地 commit-msg 钩子\n即时拦截格式与范围错误"] LocalHook --> PR["Pull Request"] PR --> CI["CI 门禁\ncommitlint + --release-notes-only"] CI --> Squash["Squash 合并进 main\n保留各子提交完整正文"] Squash --> Draft["发版汇总脚本\nFROM=上次已上架 tag"] Draft --> Edit["人工整理与多语言重写\n按新增 / 改进 / 修复排序"] Edit --> Store["双商店落盘\nApp Store JSON + Play 文本"]

这种两层分离带来两个直接收益:一是开发期心智负担极低,写一条 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 提交)。这会同时引发两个问题:

  1. 标准 Trailer 解析失效:git-interpret-trailers 只解析提交信息的最后一个段落。Squash 拼接后,前几个子提交里的 Release-Note: 落在了正文中间,会被标准 trailer 解析器静默丢弃。
  2. 多提交混合类型的分类错配:如果一个 feat PR 里顺手夹带了一个 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 的读者优先原则与两大应用商店的平台规则,整理定稿时重点守住以下约束:

写作准则

  1. 最重要的放最前:App Store 产品页默认折叠更新日志,只露出前三行左右;第一句必须让用户一眼看出这次值不值得更新。
  2. 按「新增 / 改进 / 修复」分组:组内按影响面排序,某一组为空则直接省略。
  3. 写用户所得与故障现象,不写实现:写「导出报表时不再漏掉已归档的条目」,而不是「修复查询条件过滤逻辑」。
  4. 安全修复不披露细节:涉及安全或隐私漏洞的修复只写「提升了某功能的安全性」,不描述触发路径或可利用细节。
  5. 拒绝空泛套话:避免通篇只写「修复了一些已知问题并提升了性能」。如果该版本确实只有零碎修复,挑出用户最可能感知的一两条具象写出,再以一句「以及其他稳定性改进」收尾。
  6. 付费功能明确标注:属于订阅或专业版的新增能力在句末标注(如「(Pro)」),避免免费用户更新后找不到入口产生挫败感。
  7. 按目标语言重写,不逐字翻译:各语言版本的术语与 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 发布工具链。

参考资料