提交信息书写规范

为什么需要提交信息书写规范

规范的提交信息有助于团队成员理解代码更改的目的和内容，提高代码审查和项目维护的效率。主要好处包括：

• 提高可读性：清晰的提交信息可以帮助团队成员快速理解每次更改的目的和内容。
• 简化调试：在需要回溯问题时，规范的提交信息能帮助快速定位问题的引入点。
• 改善协作：团队成员可以更容易地追踪和理解彼此的工作，减少沟通成本。
• 自动化工具支持：许多自动化工具（如CI/CD、发布工具等）可以利用提交信息进行自动化处理。

提交信息的基本结构

提交信息通常由三部分组成：

1. 标题（Header）：简明扼要地描述更改的内容。
2. 主体（Body）：详细说明更改的原因、内容和影响。
3. 页脚（Footer）：包含与提交相关的元数据（如任务编号、受影响的模块等）。

标题（Header）

标题是提交信息的第一行，应简明扼要地描述更改的主要内容。长度应限制在50个字符以内。

主体（Body）

主体部分对更改进行详细说明，包含更改的动机、内容和可能的影响。每行长度应限制在72个字符以内。

页脚（Footer）

页脚部分包含提交的元数据，如相关任务编号、受影响的模块、BREAKING CHANGE等。

提交信息的类型

为了提高提交信息的可读性和一致性，建议使用以下类型前缀：

• feat：新功能（feature）
• fix：修补bug
• docs：文档（documentation）
• style：格式（不影响代码运行的变动）
• refactor：重构（即不是新增功能，也不是修改bug的代码变动）
• test：增加测试
• chore：构建过程或辅助工具的变动

提交信息的格式

标题（Header）

<type>(<scope>): <subject>

• type：提交类型，如feat、fix、docs等。
• scope：提交影响的范围（可选），如模块、功能。
• subject：简明扼要的描述。

主体（Body）

主体部分应详细描述更改的内容和动机，必要时可以包括以下信息：

• 动机：为什么需要这次更改？
• 更改内容：具体更改了哪些内容？
• 影响：这次更改有什么潜在影响？

页脚（Footer）

页脚部分可以包括以下内容：

• 相关任务：关联的任务编号（如JIRA、Trello编号）。
• BREAKING CHANGE：如果这次提交有重大变化，应在此说明。

示例

示例1：功能提交

feat(authentication): add OAuth2 login support

Added support for OAuth2 login using Google and Facebook. This allows users to log in with their social media accounts, improving user experience and security.

BREAKING CHANGE: Updated the user model to include OAuth2 tokens. Existing users need to update their profiles.

示例2：修复提交

fix(login): correct password validation error

Fixed a bug where the password validation function incorrectly rejected valid passwords. Updated the validation regex and added additional unit tests to cover edge cases.

Closes #123

示例3：文档提交

docs(README): update setup instructions

Updated the setup instructions in the README file to include the new environment variables required for OAuth2 login.

See also #456

提交信息的最佳实践

1. 保持简洁：标题应简洁明了，不超过50个字符。
2. 详细说明：在主体部分详细描述更改内容和原因，必要时添加示例和参考链接。
3. 使用主动语态：提交信息应使用主动语态，如“Add feature”而非“Feature added”。
4. 关联任务编号：在页脚部分关联相关的任务编号，以便追踪。
5. 逐条提交：每次提交应只包含一个逻辑变动，避免过大的提交。

工具支持

为了帮助团队成员遵循提交信息书写规范，可以使用以下工具：

1. Commitizen：帮助生成符合规范的提交信息。

   npm install -g commitizen
   

   使用：

   git cz
   

2. Husky：Git hooks工具，可以在提交前自动检查提交信息。

   npm install husky --save-dev
   

3. Commitlint：用于验证提交信息是否符合规范。

   npm install @commitlint/config-conventional @commitlint/cli --save-dev
   

   配置：

   echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
   

通过以上工具，可以在提交前自动检查和生成规范的提交信息，确保团队成员遵循提交信息书写规范。

---

这份指南详细介绍了提交信息书写规范的各个方面，从基本结构到具体格式和示例，希望对你有所帮助。