Commit Message 的失落艺术：编写规范的实用指南

The Lost Art of Commit Messages

Source | HN Comments

文章探讨了编写规范的 commit message 的重要性，指出其有助于代码历史的清晰、团队协作和问题调试。文章详细介绍了 commit message 的结构，包括 `type`、`scope`、`short description`、`detailed points` 和 `footer`，并提供了每个部分的具体指南和示例。文章强调了使用标准标签、保持简洁清晰、避免冗余等原则，旨在帮助开发者写出更具信息量和可维护性的 commit message。

Commit Message 的失落艺术

你是否注意到，如今的 commit message 就像开发者们写出的隐晦的 haiku，他们似乎认为一个词就足以概括他们的杰作？人们潦草地写着 "fix bug"、"update code"，或者永远都很有描述性的 "refactor"，同时提交的代码长度堪比一部小说。好像他们认为我们都是读心者，或者他们认为他们的代码完美无瑕，不需要任何解释。

为了代码历史的清晰，让我们记住，我们不是在键盘上乱敲的猴子；我们是受过教育、有教养的人。

Commit Message 的艺术

在当今快节奏的开发世界中，编写有意义的 commit message 似乎已经成为一种失落的艺术。没错！我说的是“失落的艺术”。因为许多开发者，或者让我更正一下，许多键盘高手显然没有看到留下他们才华的可追溯线索的价值。

好的，让我们学习如何正确地做到这一点。

Commit message 是你项目历史的叙述。它们帮助其他人（以及你未来的自己）理解为什么进行这些更改，从而使协作更顺畅，调试也不再是一场噩梦。鉴于此，让我们深入研究一些指南，将你的 commit message 从模糊不清变为有价值的信息。

Commit Message 指南

每个 commit message 都应遵循以下结构：

<type>(optional scope): <short description>
<BLANK LINE>
- Optional point 1 in brief
- Optional point 2 in brief
<BLANK LINE>
<footer>

格式的组成部分

Type : 指定 commit 的性质。
Scope (可选): 受影响的组件、文件或功能的简短标识符。
Short Description : 更改的简洁摘要，最好不超过 50 个字符。
Detailed Points (可选): 提供有关更改的其他上下文或详细信息的项目符号列表。
Footer (可选): 其他元数据，例如问题引用、合作者或重大更改。

每个组成部分的指南

Type

Required : 根据 commit 的目的选择适当的类型。
仅使用允许的类型之一。

允许的类型

从以下类型中选择 <type> 字段：

feat : 一个新特性
fix : 一个 bug 修复
chore : 不影响功能的例行任务
refactor : 既不修复 bug 也不添加功能的代码更改
docs : 文档更新
style : 不影响功能的代码样式更改
test : 添加或更新测试
perf : 性能改进
ci : 持续集成更改
build : 与构建过程或依赖项相关的更改
revert : 撤消之前的 commit

Scope (可选)

Optional : 指定受影响的代码库部分。
保持简短和描述性。
使用小写和单字术语（连字符是可以接受的）。

例子：

auth, api, ui, database, config.

Short Description

Required : 用 50 个字符或更少的字符概括更改。
以小写字母开头；末尾没有标点符号。
清楚地传达更改的本质。

例子：

add user authentication
fix null pointer exception in payment module
refactor data processing pipeline

Detailed Points (可选)

Optional : 在项目符号列表中提供其他上下文。
保持每个要点简洁明了。
使用项目符号 (-) 并避免冗长的解释。

例子：

- implement OAuth2 for third-party login
- adjust timeout settings to prevent crashes
- reorganize folder structure for clarity

Footer (可选)

你可能会想，“Footer？是不是有点过分了？” 好吧，请考虑以下几点：Footer 可以自动化繁琐的任务，改善团队沟通，并使你的 commit 历史成为代码更改混乱海洋中的清晰灯塔。现在，可选的 footer 部分是你可以添加额外元数据的地方，这些元数据有助于自动化、问题跟踪并保持你的项目历史像新重构的代码库一样原始。

Footer 是 commit message 末尾的附加行，提供有关 commit 的元数据。它们可以：

Automate issue tracking : 自动关闭或引用问题和 pull request。
Provide additional context : 包括诸如合作者、签名或重大更改之类的信息。
Enhance clarity : 使你的 commit 历史更具信息性和可导航性。

常见的 Footer 标签

因为当你可以拥有_额外的_清晰度时，为什么要满足于清晰度？以下是一些你可以使用的标准 footer 标签：

BREAKING CHANGE : 表示该 commit 引入了向后不兼容的更改。
Fixes : 引用你的 commit 修复的问题。
Closes : 类似于 "Fixes"，但用于关闭问题或 pull request。
Resolves : 引用和关闭问题的另一种方式。
Related to : 链接到与 commit 相关的但未关闭它们的问题或任务。
Co-authored-by : 感谢其他贡献者。
Reviewed-by : 指示谁审查了更改。
Signed-off-by : 确认你有权提交工作的签名。
See also : 指向其他资源或相关信息。

示例 Commit Messages

示例 1：特性添加

feat(auth): add user login functionality
- implement JWT authentication
- add login endpoint to API

示例 2：修复关闭问题的 Bug

fix(ui): correct alignment on dashboard widgets
- adjust CSS flex properties
- test on multiple screen sizes
Fixes #204

示例 3：文档更新

docs(readme): update installation instructions
- add steps for setting up the development environment
- include troubleshooting tips

示例 4：代码重构

refactor(api): simplify request handlers
- remove redundant code blocks
- improve error handling mechanisms

示例 5：带有 See Also 的文档更新

docs(README): update setup instructions
- include Docker configuration
- clarify environment variables
See also: https://example.com/setup-guide

一般提示

Be concise and clear : 你未来的自己（和队友）会感谢你。
Avoid redundancy : 不要重复相同的信息。
Use present tense : "Add feature"，而不是 "Added feature"。
Be Consistent : 使用标准标签以保持 commit 历史的一致性。
Keep It Relevant : 仅包括添加价值或必要上下文的 footer。
Stay Professional : 这不是开玩笑或不必要评论的地方（那是代码注释的用途）。

下次当你忍不住输入 "fix stuff" 作为 commit message 时，请记住，我们不是猴子。我们是受过教育、有教养的人，能够清晰地传达复杂的想法。让我们确保我们的 commit message 反映了这一点，如果不是为了我们的队友，那么至少是为了防止我们未来的自己诅咒我们过去的自己。提交愉快！