用途:按 Conventional Commits(v1.0.0)规范产出格式统一的提交信息,使其可被解析为 changelog,并用于语义化版本控制。
格式:type(scope): description,随后可接可选正文与可选 footer;header 占一行,必须包含 scope,各部分之间以空行分隔。破坏性变更可在冒号前加 !,如 feat(api)!: remove v1。
类型选择:面向用户的变化用 feat(新增可见行为,如新 CLI 参数、UI 组件、API 端点)与 fix(修正行为,如修复崩溃、处理边界情况、纠正输出);维护类用 refactor(不改行为的结构调整)、perf(性能优化)、chore(删除死代码、更新工具)、style(仅格式调整)、test(仅测试文件)、build(构建系统文件)、ci(CI/CD 流水线)、docs(仅文档文件,代码注释按实际改动类型);撤销用 revert: <原提交信息>。不确定时,新用户行为用 feat,修正行为用 fix,否则用 chore 或更具体的维护类型。
description 写法:使用祈使语气,具体明确,避免 stuff、changes 等笼统词。示例:feat(auth): add passwordless login;fix(api): handle empty pagination cursor;docs(agent): add rules for dead code removal, build verification, security。
破坏性变更:在 header 用 ! 标记,或添加 BREAKING CHANGE: footer 加以说明,例如 feat(api): remove deprecated v1 endpoints,后接 BREAKING CHANGE: /v1/* endpoints are removed; migrate to /v2/*。
与语义化版本映射:fix → patch,feat → minor,任何破坏性变更(! 或 BREAKING CHANGE:)→ major。
规则:subject 用祈使语气(add 而非 added/adds),句末不加句号,长度控制在 72 字符以内,破坏性变更使用 BREAKING CHANGE: footer。被要求撰写提交信息时,先收集改动内容、scope/模块、是否面向用户以及 issue ID,再生成带可选正文与 footer 的规范 header。