Conventional Commits 规范化提交 速查备忘单

为何使用 Conventional Commits (Why Conventional Commits)

• 提交信息结构清晰、易于遵循。
• 明确表达变更的性质。
• 保证团队提交信息风格统一。
• 支持自动化版本号与 changelog 生成。
• 提交历史更易于浏览。
• 可通过 scope 进一步明确影响范围。
• 对破坏性变更有专门标注方式。
• 便于团队成员更快理解改动意图。
• 提升代码评审效率。
• 描述性提交信息有助于日后排查问题。

结构 (Structure)

<type>[可选 scope]: <description>

[可选 body]

[可选 footer(s)]

官方网站

• feat: add jwt support
• feat!: breaking change in API
• feat(ui)!: redesign user profile page
• fix: fix SQL injection vulnerability
• fix(database): resolve data race condition
• docs: update setup section of README
• style(login): correct indentation in login component
• refactor: refactor user database schema
• perf: optimize user retrieval code for faster response
• test: add tests for jwt authentication
• test(payment): add tests for the payment gateway
• chore: update build script
• chore(deps): update dependencies
• build(docker): update Dockerfile to use node 14
• ci: add job for integration tests
• revert: revert commit a1b2c3d4e5f

• 提交必须带有 type 前缀（包含名词，如 feat、fix 等），其后跟可选的 scope、 可选的 !，以及必填的末尾冒号和空格。
• 当提交向应用程序或库添加新功能时，必须使用 type feat。
• 当提交代表应用程序的 Bug 修复时，必须使用 type fix。
• 在 type 之后可以提供 scope。Scope 必须由一个描述代码库部分的圆括号包裹的名词组成， 例如 fix(parser):
• 在 type/scope 前缀后的冒号和空格之后必须紧跟 description。Description 是代码修改的简短 总结，例如 fix: array parsing issue when multiple spaces were contained in string。
• 在简短描述之后可以提供更长的提交 body，提供关于代码修改的附加上下文信息。 Body 必须始于 description 之后的一个空行。
• 提交 body 格式自由，可以由任意数量换行分隔的段落组成。
• 在 body 之后的一个空行可以提供一个或多个 footer。每个 footer 必须由一个单词 token 组成，后跟 : 或 # 分隔符，接着是字符串值（这受到了 git trailer convention 的启发）。
• Footer 的 token 必须使用 - 代替空白字符，例如 Acked-by（这有助于区分 footer 部分与多段落 body）。BREAKING CHANGE 是一个例外，也可以用作 token。
• Footer 的值可以包含空格和换行，当观察到下一个有效的 footer token/separator 对时，解析必须终止。
• Breaking changes 必须在提交的 type/scope 前缀中说明，或者作为 footer 中的一个条目。
• 如果作为 footer 包含，breaking change 必须由大写文本 BREAKING CHANGE 组成，后跟冒号、 空格和描述，例如 BREAKING CHANGE: environment variables now take precedence over config files。
• 如果包含在 type/scope 前缀中，breaking changes 必须在 : 紧前用 ! 说明。如果使用了 !，BREAKING CHANGE: 可以从 footer 部分省略，并且提交描述应用于描述 breaking change。
• 在您的提交信息中可以使用 feat 和 fix 之外的 type，例如 docs: update ref docs。
• 组成 Conventional Commits 的信息单元在实现时不得处理为区分大小写，但 BREAKING CHANGE 除外，它必须大写。
• 在 footer 中用作 token 时，BREAKING-CHANGE 必须与 BREAKING CHANGE 同义。