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-productivitySuper 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导致用户可见的改动从发布说明中丢失。因此本仓库的提交信息规范包含三层目的人类可读一眼看出这次改动是新增功能、修 bug 还是重构机器可解析供 tools/release-notes.js 等脚本与 CI 流程自动聚合、分类、生成发布说明团队纪律通过.github/PULL_REQUEST_TEMPLATE.md中的 Checklist 约束每个 PR 的提交历史。二、核心格式type(scope): description规范的核心是一条单行模板type(scope): descriptiontype改动类型限定词表scope本次改动触及的功能/区域名tasks、sync、ui、plugins等description以祈使句写成的简短描述。支持的 type 词表文档明确列出的十种类型type语义典型场景feat新功能新增重复任务支持fix缺陷修复处理同步网络超时docs文档改动修正 README、wiki 链接style样式/格式格式化、无逻辑变化的样式调整refactor重构不改行为的代码结构重组perf性能优化减少大列表渲染开销test测试改动覆盖向量时钟剪枝的测试build构建系统依赖、构建配置改动ciCI 配置工作流脚本改动chore杂务不落入以上类型的维护性改动其中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注意两处细节scope 必须与被改动的功能/区域对应tasks、sync、ui、plugins…使发布说明能按模块分组例如 release 脚本的toBulletLines会输出**sync:** ...这样的带 scope 强调的分组条目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):这是本技能文档最具特色的规则措辞为绝对禁止NeverNeverfix(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之外仓库还有两处对提交信息的配套约束.github/CONTRIBUTING.md声明使用 Angular 提交格式并补充一条规则——修复具体 issue 时在描述中带上 issue 编号例如feat: add nice feature #31。这使提交与问题追踪系统可双向追溯AI Agent 场景该 SKILL.md 位于.agents/skills/目录frontmatter 中的description字段明确说明其触发条件——when committing, crafting a commit message, or squashing提交、撰写提交信息或 squash 时。也就是说无论是人类开发者还是接入仓库的 AI Agent提交信息都遵循同一套格式与 test-scope 规则避免自动化改写破坏发布流水线的解析。七、提交规范如何贯通发布流水线将以上规则串联起来可以看到一条完整的自动化链路开发者按type(scope): description撰写提交npm run prepare触发 husky见 package.json 的prepare脚本与 package.json 的 husky 依赖在提交钩子层面建立格式纪律版本发布时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同一脚本将用户可见提交写成纯文本 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/chorescope 指向实际改动的功能/区域仅仓库级改动才省略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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-productivitySuper 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导致用户可见的改动从发布说明中丢失。因此本仓库的提交信息规范包含三层目的人类可读一眼看出这次改动是新增功能、修 bug 还是重构机器可解析供 tools/release-notes.js 等脚本与 CI 流程自动聚合、分类、生成发布说明团队纪律通过.github/PULL_REQUEST_TEMPLATE.md中的 Checklist 约束每个 PR 的提交历史。二、核心格式type(scope): description规范的核心是一条单行模板type(scope): descriptiontype改动类型限定词表scope本次改动触及的功能/区域名tasks、sync、ui、plugins等description以祈使句写成的简短描述。支持的 type 词表文档明确列出的十种类型type语义典型场景feat新功能新增重复任务支持fix缺陷修复处理同步网络超时docs文档改动修正 README、wiki 链接style样式/格式格式化、无逻辑变化的样式调整refactor重构不改行为的代码结构重组perf性能优化减少大列表渲染开销test测试改动覆盖向量时钟剪枝的测试build构建系统依赖、构建配置改动ciCI 配置工作流脚本改动chore杂务不落入以上类型的维护性改动其中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注意两处细节scope 必须与被改动的功能/区域对应tasks、sync、ui、plugins…使发布说明能按模块分组例如 release 脚本的toBulletLines会输出**sync:** ...这样的带 scope 强调的分组条目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):这是本技能文档最具特色的规则措辞为绝对禁止NeverNeverfix(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之外仓库还有两处对提交信息的配套约束.github/CONTRIBUTING.md声明使用 Angular 提交格式并补充一条规则——修复具体 issue 时在描述中带上 issue 编号例如feat: add nice feature #31。这使提交与问题追踪系统可双向追溯AI Agent 场景该 SKILL.md 位于.agents/skills/目录frontmatter 中的description字段明确说明其触发条件——when committing, crafting a commit message, or squashing提交、撰写提交信息或 squash 时。也就是说无论是人类开发者还是接入仓库的 AI Agent提交信息都遵循同一套格式与 test-scope 规则避免自动化改写破坏发布流水线的解析。七、提交规范如何贯通发布流水线将以上规则串联起来可以看到一条完整的自动化链路开发者按type(scope): description撰写提交npm run prepare触发 husky见 package.json 的prepare脚本与 package.json 的 husky 依赖在提交钩子层面建立格式纪律版本发布时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同一脚本将用户可见提交写成纯文本 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/chorescope 指向实际改动的功能/区域仅仓库级改动才省略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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考