前端代码规范 - Commit 提交规范

什么是约定式提交？

约定式提交（Conventional Commits）是一种用于代码版本控制的规范，旨在通过标准化提交信息结构，提升代码协作的质量和效率。该规范通过规定提交信息的结构和语义，使代码版本控制的可读性、可维护性和自动化程度得到显著提高。

提交信息的结构

提交信息通常包括以下部分：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• 类型：例如 feat（新功能）、fix（修复错误）、docs（文档变更）等。
• 范围（可选）：提交影响的模块或功能。
• 描述：简短描述提交内容。
• 正文（可选）：对提交的详细描述。
• 脚注（可选）：包含额外的信息，如 BREAKING CHANGE。

示例

1. 描述和破坏性变更的提交：

   feat: allow provided config object to extend other configs
   
   BREAKING CHANGE: `extends` key in config file is now used for extending other config files
   

2. 带有 ! 标识的破坏性变更提交：

   feat!: send an email to the customer when a product is shipped
   

3. 包含范围的提交：

   feat(api)!: send an email to the customer when a product is shipped
   

4. 不包含正文的提交：

   docs: correct spelling of CHANGELOG
   

5. 包含多行正文和多行脚注的提交：

   fix: prevent racing of requests
   
   Introduce a request id and a reference to latest request. Dismiss
   incoming responses other than from latest request.
   
   Remove timeouts which were used to mitigate the racing issue but are
   obsolete now.
   
   Reviewed-by: Z
   Refs: #123
   

类型概览

为什么需要约定式提交？

Git 提交信息遵循 Angular 约定可以使提交信息格式更加清晰、易读，从而提高代码协作效率。Angular 约定包含三个部分：

1. 标题（header）：简短描述更改内容，并指定更改类型和影响范围。
2. 正文（body）：提供更详细的更改描述，包括原因、影响和解决方案。
3. 页脚（footer）：提供附加信息，如相关链接、关联的 BUG 编号等。

通过遵循这些约定，团队成员可以更好地理解代码更改的意图，并与自动化工具更好地集成，如自动版本控制、代码审查工具等。

如何遵守约定式提交？

第一步：使用 Commitizen 生成提交说明

Commitizen 是一个命令行工具，帮助开发者生成符合规范的 Git 提交信息。以下是安装和使用步骤：

1. 全局安装 Commitizen 和 cz-conventional-changelog：

   pnpm install -g commitizen cz-conventional-changelog
   

2. 创建 .czrc 文件：

   echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
   

3. 使用 Commitizen 生成提交说明：

   git cz
   

第二步：自定义提交信息

通过 cz-customizable 插件，开发者可以根据项目需求自定义提交信息格式。

1. 安装 cz-customizable：

   npm install cz-customizable --save-dev
   

2. 添加配置到 package.json：

   "config": {
     "commitizen": {
       "path": "node_modules/cz-customizable"
     }
   }
   

3. 在项目根目录下创建 .cz-config.js 文件自定义提示：

   module.exports = {
     types: [
       { value: ':sparkles: feat', name: '✨ feat: 新功能' },
       { value: ':bug: fix', name: '? fix: 修复' },
       // 其他类型省略...
     ],
     messages: {
       type: '请选择提交的类型：',
       customScope: '请输入修改的范围(可选)',
       subject: '请简要描述提交(必填)',
       body: '请输入详细描述(可选)',
       footer: '请输入要关闭的 issues(可选)',
       confirmCommit: '确认要使用以上信息提交？(y/n)'
     },
     subjectLimit: 72
   };
   

第三步：增加对提交信息的校验

为了确保提交信息符合规范，可以使用 commitlint 进行校验。

1. 安装 @commitlint/config-conventional 和 @commitlint/cli：

   npm i @commitlint/config-conventional @commitlint/cli -D
   

2. 在根目录创建 commitlint.config.js 文件：

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

进一步提升提交质量：使用 Husky 和 lint-staged

Husky 可以帮助在提交代码前执行格式化、测试等操作，而 lint-staged 可对暂存区代码进行 ESLint 校验和 Prettier 格式化。

1. 安装 Husky：

   pnpm install husky --save-dev
   

2. 在 package.json 中配置 Git hooks 和对应的脚本：

   "husky": {
     "hooks": {
       "pre-commit": "npm run lint && npm run test"
     }
   }
   

3. 安装 lint-staged 并配置：

   npm i lint-staged --save-dev
   

   在 package.json 中新增配置：

   "lint-staged": {
     "/**/*.{js,jsx,tsx,ts,less,scss,md,json}": [
       "prettier --write"
     ]
   }
   

通过这些步骤，确保提交的信息规范，代码在提交前经过自动化的格式化和校验，从而提高代码质量和团队协作效率。