SuperAPI AI 工具集

conventional-commits

编程与开发

查看项目

更新于 10-19 19:24

技能介绍

Conventional Commits 技能用于指导编写符合 Conventional Commits 规范(v1.0.0)的 Git 提交信息,使提交历史同时具备人类可读与机器可读的含义,便于理解项目变更并改善协作。

适用场景:创建 Git 提交、审查 PR 中的提交信息、撰写清晰结构化的提交信息、多人协作项目。

提交信息基本结构为:<type>[optional scope]: <description>,其后可选正文与页脚。示例包括 feat: add user authentication、feat(api): add JWT token generation、fix: resolve memory leak in image processor、docs: update README with setup instructions、refactor(database): optimize user query performance。

主要类型:feat(新功能)、fix(缺陷修复)、docs(仅文档)、style(不影响代码含义的格式改动)、refactor(既不修复缺陷也不新增功能的代码改动)、perf(性能改进)、test(新增或更新测试)、chore(构建流程、依赖或维护性改动);较少使用的还有 build(构建系统或依赖)、ci(CI 配置)、revert(回滚此前提交,如 revert: revert "feat: add export feature",并附 This reverts commit abc123.)。

范围可选,用于说明代码库中改动的部分,如 auth、api、ui、database 或 db、services、jobs、tests、deps、config、docs,应结合项目架构与领域选择。

描述规则:使用祈使语气现在时(add 而非 added 或 adds);首字母不大写;结尾不加句号;尽量控制在 72 字符内(理想 50 字符内)。反例包括过去时、首字母大写、结尾句号以及含糊表述。

正文可选,用于说明复杂改动、非显而易见的设计决策、破坏性变更、迁移说明;与描述之间空一行,保持祈使语气,按 72 字符换行,可分多段。

页脚可选,用于元数据:破坏性变更可用 BREAKING CHANGE: 页脚,或在类型/范围后加 !(如 feat!: ...、feat(api)!: ...);议题引用可用 Fixes #123、Closes #456、Resolves #123、Related to #789、See also #123;共同作者使用 Co-authored-by: 姓名 <邮箱>。

最佳实践:使用现在时祈使语气;首行尽量少于 50 字符;在页脚引用议题或 PR;正文解释“为什么”而非“做了什么”;将大改动拆分为多个提交;保持提交原子性(每个提交一个逻辑变更)。避免含糊描述、混入无关改动、首字母大写、结尾句号、过去时,以及提交无法运行的代码。

限制:资料仅提供撰写规范与示例,未提供具体安装命令、工具集成方式或自动化校验实现,暂未提供。更多详细示例与边界情况可参见 references/commit-examples.md。