规范

----现代软件架构的复杂性需要协同开发完成，如何高效地协同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶。对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

代码规范：阿里巴巴 Java 开发手册

注释规范：中文技术文档的写作规范

Git Commit Message：conventional-changelog 标准

1.1 emoji 工具 git emoji

emoji	emoji 代码	commit 说明
✨	`:sparkles:`	feat ：新功能（feature）
🐛	`:bug:`	fix ：修补bug
📝	`:memo:`	docs ：文档（documentation）
💄	`:lipstick:`	style ：格式（不影响代码运行的变动）
♻️	`:recycle:`	refactor ：重构（即不是新增功能，也不是修改bug的代码变动）
⚡️	`:zap:`	perf ：性能、体验优化
✅	`:white_check_mark:`	test ：增加、更新测试
👷	`:construction_worker:`	build ：构建过程或辅助工具的变动
⏪	`:rewind:`	revert ：回滚某个提交
➖	`:heavy_minus_sign:`	降级依赖项
➕	`:heavy_plus_sign:`	升级依赖项
📦	`:package:`	添加或更新编译的文件或

Git 每次提交代码时，都要写 Commit message（提交说明），对于一个规范的 commit message 可以带给我们：

提供更多的历史信息，方便快速浏览；
可以过滤某些 commit（比如文档改动），便于快速查找信息；
可以直接根据 commit 生成 Change log 文件生成版本升级文档。

所以，规范 git commit 对于提高 git log 可读性、版本控制和 changelog 生成都有着重要的作用。

下面我们从 Commit message 格式、以及如何规范约束 commit 来学习使用。

Commit message 格式

Commit message 包括三个部分：Header，Body 和 Footer。结构如下：

<类型>([可选的作用域]): <描述> - header
// 空一格
[可选的正文] - body
// 空一格
[可选的脚注] - footer
复制代码

其中，Header 是必需的，Body 和 Footer 可以省略。通常我们只需要编写 Header 即可。

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。

1、type：
type 用于说明 commit 的类别，一般允许使用下面7个标识。

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

并且 type会被用于生成 changlog，如果 type为 feat和 fix，则该 commit 将肯定出现在 Change log 之中。

2、scope：
scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

3、subject：
subject是 commit 目的的简短描述，不超过50个字符。

Commit 前的代码校验

在执行 git commit之前，需要进行代码规则检查能够确保进入 git 库的代码都是符合代码规则的。我们可以借助两个工具包来实现：lint-staged 和 husky。

lint-staged：由于整个项目上运行 lint 速度会很慢，lint-staged 能够让 lint 只检测暂存区的文件；
husky：可以让我们在项目中方便添加 git hooks。

1、安装：

npm install lint-staged husky@^4.3.8 -D
复制代码

注意，上面我们指定了 husky 版本，如果不指定版本号，将安装最新版本 husky（6.0.0以上），配置方式会有所不同，具体步骤可参考文档配置。

2、在 package.json 中配置：

"scripts": {
  "lint": "eslint src --ext .js,.jsx,.ts,.tsx"
},
"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "src/**/*.{js,json,css,scss,ts,tsx,md}": [
    "eslint"
  ]
},
复制代码

3、使用：
首先确保项目内配置了 ESLint，参考配置可以看这里。我们在 src/index.js 编写一个不规范的代码，执行：

git add .
git commit -m 'feat: 配置 commit lint code'
复制代码

当变更文件内的代码校验不合格时，会中断提交。

规范 Commit message

Commitizen 是一个撰写合格 Commit message 的工具，提供了一组 Header.type 可选列表来规范 commit message。

1、安装：

npm install commitizen cz-conventional-changelog -D
复制代码

2、在 package.json 内进行配置（使用业界 Angular 的 Commit message 格式）：

"config":{
  "commitizen":{
    "path":"./node_modules/cz-conventional-changelog"
  }
},
复制代码

3、添加执行 commit 脚本：

"scripts": {
  "commit": "git-cz",
}
复制代码

注意这里，凡是用到 git commit 命令，一律改为使用 git-cz。这时，就会出现选项，用来生成符合格式的 Commit message。

4、执行：

npm run commit
复制代码

生成 CHANGELOG

当我们有了规范的 Commit message 后，就可以根据它们自动生成 CHANGELOG.md。

1、安装：

npm install conventional-changelog-cli -D
复制代码

2、在 package.json 中配置执行脚本：

"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
}
复制代码

-p angular：指定风格，用来指定使用的 commit message 标准；
-i CHANGELOG.md: 指定输出的文件名称；
-s：指定读写同一文件；
-r 0：指定增量更新，不会覆盖以前的更新日志。

默认 -i 会在工程根目录下生成 CHANGELOG.md 文件，如果想输出到指定目录下，比如在 docs 目录下生成，可以使用 -i ./docs/CHANGELOG.md。（前提需要确保目录存在）

注意：上面命令不会覆盖以前的 Change log，只会在 CHANGELOG.md 的头部加上自从上次发布以来的变动。

如果你想生成一个完整的 Change log 到 CHANGELOG.md 文件，需要运行下面的命令：

"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
}
复制代码

3、执行：

npm run changelog