Super Productivity 提交信息规范：Angular Conventional Commit 格式与 test-scope 规则实战指南

Super Productivity 提交信息规范：Angular Conventional Commit 格式与 test-scope 规则实战指南

【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity

Super Productivity 是一个基于 Angular + Electron + Capacitor 的开源待办与时间追踪应用，其仓库通过.agents/skills/commit-messages/SKILL.md为开发者和 AI Agent 固化了一套统一的提交信息规范：Angular conventional-commit 格式type(scope): description，并辅以一条极具项目特色的 test-scope 硬性规则。本文以该技能文档为骨架，结合仓库内的贡献指南、Pull Request 模板与发布脚本源码，系统讲解如何写出符合规范、可被自动化工具解析的提交信息，帮助你与 CI、发布流水线顺畅协作。

一、规范总览：为什么需要统一提交信息

在 Super Productivity 仓库中，提交信息不是写给 Git 日志看的装饰品，而是被真实工具消费的结构化数据。以 tools/release-notes.js 为例，它在版本发布时执行git log抓取提交主题，并用正则^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)$（见 parseCommitSubject）解析出type、scope、description三个字段，再据此自动分组生成 GitHub Release Notes 与 Google Play 变更日志。提交信息若不遵循规范，就会被解析为type: null并归入 "Other Changes"，导致用户可见的改动从发布说明中丢失。

因此，本仓库的提交信息规范包含三层目的：

1. 人类可读：一眼看出这次改动是新增功能、修 bug 还是重构；
2. 机器可解析：供 tools/release-notes.js 等脚本与 CI 流程自动聚合、分类、生成发布说明；
3. 团队纪律：通过.github/PULL_REQUEST_TEMPLATE.md中的 Checklist 约束每个 PR 的提交历史。

二、核心格式：type(scope): description

规范的核心是一条单行模板：

type(scope): description

• type：改动类型，限定词表；
• scope：本次改动触及的功能/区域名（tasks、sync、ui、plugins等）；
• description：以祈使句写成的简短描述。

支持的 type 词表

文档明确列出的十种类型：

其中feat、fix、perf三种类型在发布脚本中被标记为user-facing（用户可见）——对照 USER_FACING_TYPES，它们会被优先聚合进 GitHub 与 Play Store 的发布说明；而build、chore、ci、docs、refactor、style、test被归为低信号类型（LOW_SIGNAL_TYPES），仅在无其他改动时才兜底展示。

格式示例

feat(tasks): add recurring task support fix(sync): handle network timeout

注意两处细节：

1. scope 必须与被改动的功能/区域对应（tasks、sync、ui、plugins…），使发布说明能按模块分组，例如 release 脚本的toBulletLines会输出**sync:** ...这样的带 scope 强调的分组条目；
2. scope 仅在改动真正横跨整个仓库时才允许省略。若每次提交都省略 scope，发布说明就失去模块维度，分组价值大打折扣。

三、description 的三条硬性规则

技能文档对描述部分给出三条强制约束：

• 祈使句（imperative）：把描述写成"下达指令"的口吻，如add、handle、cover，而不是added、handling、covers。这与 Git 官方提交指南一致——提交描述应当能补全句子 "If applied, this commit will …"；
• 全小写（lower-case）：首字母与一般名词保持小写，不使用句首大写；
• 结尾不加句点（no trailing period）：描述末尾不写.，保持单行紧凑。

实践示例：

# ✅ 正确 feat(tasks): add recurring task support fix(sync): handle network timeout test(sync): cover vector-clock pruning # ❌ 错误 feat(tasks): Added recurring task support. # 过去式 + 大写 + 句点 FIX(sync): handle network timeout # type 大写 fix(sync): handle network timeout. # 结尾句点

四、test-scope 规则：test:而不是fix(test):

这是本技能文档最具特色的规则，措辞为绝对禁止（Never）：

Neverfix(test):orfix(e2e):— changes to tests use thetest:type.

也就是说，测试相关改动（包括修复测试代码、修复 E2E 用例、补充测试覆盖）一律使用test:类型，例如文档给出的test(sync): cover vector-clock pruning；不允许写成fix(test): ...或fix(e2e): ...。

其背后逻辑在 .github/CONTRIBUTING.md 中有直接说明：fix类型保留给真正的代码/缺陷修复。如果测试失败本身是产品代码 bug 的表现，那么修复对象是产品代码，应写fix(...)；若只是测试用例本身有误或被调整，则属于test类型。这样分类的价值同样落在发布说明上——test:属于低信号类型，不会污染面向用户的 Release Notes，而误用fix(test):会把"修测试"伪装成"修 bug"展示给用户。

配套实践：.github/PULL_REQUEST_TEMPLATE.md的 Checklist 要求 "I have added tests for my changes (if applicable)"，说明测试改动是常规 PR 的一部分，因此有一条清晰、无歧义的分类规则尤为重要。

五、scope 的选择与省略边界

• scope 取被改动的主要功能/区域：tasks、sync、ui、plugins均为文档给出的合法取值。对应仓库结构，src/app/features/tasks/是任务模块热区，src/app/op-log/与packages/sync-core/、packages/sync-providers/构成同步子系统，src/app/plugins/为插件框架——这些目录名就是天然的 scope 来源；
• 仅当改动真正横跨整个仓库时才省略 scope：例如一次纯全局的格式化或依赖升级，写chore: ...即可；凡是能定位到模块的改动，都应带上 scope，以保证发布说明分组的完整性。

六、配套规范：issue 编号与 AI Agent 使用场景

除了.agents/skills/commit-messages/SKILL.md之外，仓库还有两处对提交信息的配套约束：

1. .github/CONTRIBUTING.md：声明使用 Angular 提交格式，并补充一条规则——修复具体 issue 时在描述中带上 issue 编号，例如feat: add nice feature #31。这使提交与问题追踪系统可双向追溯；
2. AI Agent 场景：该 SKILL.md 位于.agents/skills/目录，frontmatter 中的description字段明确说明其触发条件——"when committing, crafting a commit message, or squashing"（提交、撰写提交信息或 squash 时）。也就是说，无论是人类开发者还是接入仓库的 AI Agent，提交信息都遵循同一套格式与 test-scope 规则，避免自动化改写破坏发布流水线的解析。

七、提交规范如何贯通发布流水线

将以上规则串联起来，可以看到一条完整的自动化链路：

1. 开发者按type(scope): description撰写提交，npm run prepare触发 husky（见 package.json 的prepare脚本与 package.json 的 husky 依赖），在提交钩子层面建立格式纪律；
2. 版本发布时，tools/release-notes.js 通过parseCommitSubject正则解析提交主题，USER_FACING_TYPES/LOW_SIGNAL_TYPES区分用户可见改动，GITHUB_GROUPS（见 tools/release-notes.js）将提交聚合成 Features / Fixes / Performance / Other Changes 四类，自动生成 GitHub Release Notes；
3. 同一脚本将用户可见提交写成纯文本 bullet，截断至 500 字符后输出为 Google Play 变更日志（PLAY_STORE_MAX_CHARS），从而保证提交信息的质量直接决定商店页面与发布说明的质量。

这也解释了为什么 test-scope 规则如此强硬：一次fix(e2e): ...就会让"修复不稳定测试"被误报为面向用户的修复，污染整个发布说明。

八、快速自查清单

提交前对照以下清单逐项检查：

• 使用type(scope): description单行格式
• type 属于十种词表（feat/fix/docs/style/refactor/perf/test/build/ci/chore）
• scope 指向实际改动的功能/区域；仅仓库级改动才省略
• description 为祈使句、全小写、无结尾句点
• 测试改动一律用test:，绝不使用fix(test):或fix(e2e):
• 修复 issue 时在描述末尾追加#编号（如feat: add nice feature #31）
• 发布说明依赖该格式自动生成，切勿使用自由格式提交

遵循这套规范，你的每次提交不仅是一行整洁的 Git 历史，更是驱动 Super Productivity 自动化发布链路的高质量数据源。

【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity