conventional-commits

Conventional Commits

创建易于审查且能通过 cog verify 的提交和 PR 标题。

必需格式

使用 Conventional Commits：

type(scope): imperative subject

作用域可选：

fix: handle empty setup files
feat(setups): add rust CLI preset
docs(readme): clarify setup install commands

允许的类型

• feat - 面向用户的功能或能力
• fix - 修复错误
• refactor - 不改变行为的代码变更
• docs - 仅文档变更
• test - 仅测试变更
• chore - 不改变运行时行为的维护工作
• build - 构建工具、依赖项或打包
• ci - CI 工作流变更
• perf - 性能改进
• style - 仅格式调整，不涉及 UI 视觉变更
• revert - 撤销先前的变更

主题规则

• 使用祈使语气：add、fix、remove、rename；不要使用 added、fixed、removes。
• 冒号后以小写字母开头。
• 末尾不要加句号。
• 尽量将首行控制在 72 个字符以内。
• 描述意图，而非文件名。

提交工作流

1. 检查工作树：

   • git status --short
   • git diff --stat
   • git diff

2. 确定提交边界。

   • 将无关变更拆分为单独的提交。
   • 如果行为、测试、文档、格式、依赖项和生成文件的变更可分别审查，则将其拆分。
   • 如果同一文件中包含不同类型的变更，使用补丁暂存。

3. 仅暂存预期变更。

   • 对于边界清晰的文件，使用 git add <path>。
   • 对于包含混合变更的代码块，使用 git add -p。
   • 使用 git diff --cached 检查已暂存内容。

4. 编写提交消息。

   • 从允许的列表中选择类型。
   • 在有助于审查时添加作用域，通常是软件包、模块、集合或功能。
   • 仅在原因不明显时添加正文。
   • 使用脚注标记 BREAKING CHANGE:、Refs #123 或 Closes #123。

5. 在 Cocogitto 可用时进行验证。

   • cog verify "$(git log -1 --pretty=%B)"
   • 验证拟定的标题：cog verify "$PR_TITLE"

6. 提交前运行最小范围的相关验证；如果仓库有规定的验证命令，则使用该命令。

PR 标题规则

拉取请求标题也必须遵循 Conventional Commits，因为 squash merge 通常会使用 PR 标题作为最终提交消息。

打开或编辑 PR 之前：

PR_TITLE='feat(setups): add Go CLI preset'
cog verify "$PR_TITLE"

如果未安装 cog，仍需严格按照 Conventional Commit 格式编写标题，并预期 CI 会进行验证。

示例

正确：

feat(auth): add token refresh flow

包含正文的正确示例：

fix(cli): handle empty setup files

The installer previously treated an empty setup file as a successful install.
This now fails early with a clear error.

错误：

update files

错误：

fix: change setup line 42

输出

收到提交请求时，请报告：

• 选择的提交边界
• 每个提交暂存的文件
• 最终提交消息
• 验证命令及结果