技术: Git 代码规范

本文主要讲述在 Git 工作流中一系列书写规范问题.

归纳起来如下:

• commit 信息怎么写
• change log怎么写
• 分支名的命名规范

提交信息

同一组里就会看到有些人, 直接 git commit -m "xxxx" 就提交了, 事后除了问题, 要回退版本, 就非常不友好. 所以在提交的时候, 就会要求好规范.
规范的提交, 给一个直接例子:

refactor(sns): simplify conditional display

什么意思? 下面解释一下.

Header

头部分就是冒号前面的部分, 主要包括3个子部分:

• type
• scope
• subject

type用于说明 commit 的类别，只允许使用下面 7 个标识:

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

scope用于说明受影响的范围, 比如模块, 代码包等. 一般紧跟在type后面的圆括号内.

subject用于描述本次commit的目的, 放在冒号的后面 (第一个字母小写, 结尾不加句号)

以动词开头，使用第一人称现在时，比如change，而不是changed或changes

Body

Body 部分是对本次 commit 的详细描述，说明具体更改了哪些东西, 并且使用现代时.
可以分成多行, 但每一行, 都要顶头写, 可以使用*进行缩进.
例如:

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so.
Further paragraphs come after blank lines.
 * Bullet points are okay, too

Footer

一般会用到footer都是比较特殊的情况, 比如关于一个issue, 它完全可以作为一个独立的部分.也就是说:

普通的提交, 是没有Footer, 只要特殊情况才会用到footer, 并且本次提交中header,body的写法都会改变.

例如:

BREAKING CHANGE: isolate scope bindings definition has changed.

To migrate the code follow the example below:

Before:

scope: {
  myAttr: 'attribute',
}

After:

scope: {
  myAttr: '@',
}

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

如果当前代码与上一个版本不兼容，则 Footer 部分以BREAKING CHANGE开头(突破性更新)，后面是对变动的描述、以及变动理由和迁移方法。

或者另外一种情况: 关闭issue;
此时, 你的header, body, 还是按照规范写, 但是在组后面, 写上一行. Closes #234 或者 Closes #123, #245, #992

特殊情况

revert的情况比较特殊,

如果当前 commit 用于撤销以前的 commit，则必须以 revert: 开头，后面跟着被撤销 Commit 的 Header

例如:

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body 部分的格式是固定的，必须写成This reverts commit <hash>.， 其中的 hash 是被撤销 commit 的 SHA 标识符.

如果当前 commit 与被撤销的 commit，在同一个发布（release）里面，那么它们都不会出现在 Change log 里面。(当做没发生)
如果两者在不同的发布，那么当前 commit，会出现在 Change log 的 Reverts 小标题下面。

下面就说说, release版本时, 变更日志.

变更日志

一般用于产品发布的时候, 内部详细记录. 当一个阶段的开发以后，就应该推出更新日志。

• 对于开发者，这是对过去一段时间自己开发的总结；
• 对于用户，更新日志是他们了解你开发成果的渠道。

先看成熟产品的CHANGELOG.md是怎么写的:

一个好的更新日志可以清楚地展现你这一段时间的成果，应该包括你修复的 Bug、你新增的 Feature、你做的改动;
以及突破性变更（一般这类改动会改变用户过去的操作习惯、或者需要用户对其作出新的配置，以及其它包含不向下兼容的改动）

其实规则也很简单:

• New features
• Changes
• Bugs fixed

每个部分尽量罗列相关的 commit ，并且有指向这些 commit 的链接。

分支命名

新加的功能或者特性加入主分支, 实在太过冒险，虽然出了严重的问题可以revert, 但是这应该是最坏的打算.

正确做法是把有风险和较大的改动都要新建一个分支进行管理，在新的分支里进行提交。当功能已经完善以后，把分支 Pull Rquest 合并回主分支。
这样，就算其它分支改残了，主分支依然是合理和完美的, 而且不同的人协同开发时，可以尽量用不同的分支，互不冲突。

分支的命名规范如下, 包含三个部分, 以\分割:

• type
• scope
• subject

举一些简单的例子:

fix/jsload , fix/comment/disqusclick, feat/sidebar 等

Type

A type is used to mark what the branch used for, 通俗说, 就是分支的工作类型.
There are some examples: (后面跟的是解释)

• feat: New Feature
• fix: Fix a bug
• docs: About Documentiations
• style: Format (And it won’t affect the code running)
• refactor: Refactor(No new feature will be added or no bugs will be fixed)
• test: Test
• chore: Update our tools

Scope

It is used to explain which parts will this branch mainly affected.

一般就是指具体的某个代码模块.

Subject

该部分非必要, 除非你的模块太大了, 需要具体指定影响了哪些目标; 或者, 说明建立分支理由.

该部分通常没有必要, 写了反而啰嗦

说明

本文参考了 angular 的提交规范: https://github.com/angular