Skip to content

Commit f573027

Browse files
zjykzjzjykzj
committed
docs(message): add
1 parent 272f8b6 commit f573027

File tree

8 files changed

+548
-10
lines changed

8 files changed

+548
-10
lines changed

‎docs/index.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
# GitGuide
22

33
* 规范
4-
* README编写
4+
* `GIT`工作流
5+
* `README`编写
56
* 消息提交
67
* 版本提交
7-
* GIT工作流
88
* 工具
9-
* Git
10-
* Commitizen
11-
* conventioanl-changelog
12-
* CommitLint+Husky
13-
* generator-standard-readme
9+
* `Git`
10+
* `Commitizen`
11+
* `conventioanl-changelog`
12+
* `CommitLint+Husky`
13+
* `generator-standard-readme`
1414
* 平台
15-
* GitLab
16-
* GitHub
15+
* `GitLab`
16+
* `GitHub`

‎docs/message/angular-commit.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
2+
# Angular提交规范
3+
4+
目前最受开发人员肯定的规范是前端框架`Angular`提出的[Angular提交信息规范](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)
5+
6+
提交格式如下：
7+
8+
<type>(<scope>): <subject>
9+
<BLANK LINE>
10+
<body>
11+
<BLANK LINE>
12+
<footer>
13+
14+
每次提交可以包含页眉(`header`)、正文(`body`)和页脚(`footer`)，每次提交**必须包含页眉内容**
15+
16+
每次提交的信息不超过`100`个字符
17+
18+
详细文档：[AngularJS Git Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#)
19+
20+
## 页眉设置
21+
22+
页眉的格式指定为提交类型(`type`)、作用域(`scope`，可选)和主题(`subject`)
23+
24+
### 提交类型
25+
26+
提交类型指定为下面其中一个：
27+
28+
1. `build`：对构建系统或者外部依赖项进行了修改
29+
2. `ci`：对CI配置文件或脚本进行了修改
30+
3. `docs`：对文档进行了修改
31+
4. `feat`：增加新的特征
32+
5. `fix`：修复`bug`
33+
6. `pref`：提高性能的代码更改
34+
7. `refactor`：既不是修复`bug`也不是添加特征的代码重构
35+
8. `style`：不影响代码含义的修改，比如空格、格式化、缺失的分号等
36+
9. `test`：增加确实的测试或者矫正已存在的测试
37+
38+
### 作用域
39+
40+
范围可以是任何指定提交更改位置的内容
41+
42+
### 主题
43+
44+
主题包括了对本次修改的简洁描述，有以下准则
45+
46+
1. 使用命令式，现在时态：“改变”不是“已改变”也不是“改变了”
47+
2. 不要大写首字母
48+
3. 不在末尾添加句号
49+
50+
## 正文设置
51+
52+
和主题设置类似，使用命令式、现在时态
53+
54+
应该包含修改的动机以及和之前行为的对比
55+
56+
## 页脚设置
57+
58+
### Breaking changes
59+
60+
不兼容修改指的是本次提交修改了不兼容之前版本的`API`或者环境变量
61+
62+
所有不兼容修改都必须在页脚中作为中断更改块提到，以`BREAKING CHANGE`:开头，后跟一个空格或者两个换行符，其余的信息就是对此次修改的描述，修改的理由和修改注释
63+
64+
BREAKING CHANGE: isolate scope bindings definition has changed and
65+
the inject option for the directive controller injection was removed.
66+
67+
To migrate the code follow the example below:
68+
69+
Before:
70+
71+
。。。
72+
。。。
73+
74+
After:
75+
76+
。。。
77+
。。。
78+
79+
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
80+
81+
### 引用提交的问题
82+
83+
如果本次提交目的是修改`issue`的话，需要在页脚引用该`issue`
84+
85+
以关键字`Closes`开头，比如
86+
87+
Closes #234
88+
89+
如果修改了多个`bug`，以逗号隔开
90+
91+
Closes #123, #245, #992
92+
93+
## 回滚设置
94+
95+
当此次提交包含回滚(`revert`)操作，那么页眉以`"revert:"`开头，同时在正文中添加`"This reverts commit hash"`，其中`hash`值表示被回滚前的提交
96+
97+
revert:<type>(<scope>): <subject>
98+
<BLANK LINE>
99+
This reverts commit hash
100+
<other-body>
101+
<BLANK LINE>
102+
<footer>

‎docs/message/conventional-commit.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
2+
# Conventional提交规范
3+
4+
[Conventional Commits](https://www.conventionalcommits.org)(约定式提交)脱胎于`Angular`提交信息准则，提供了更加通用、简洁和灵活的提交规范
5+
6+
提交格式如下：
7+
8+
<类型>[可选的作用域]: <描述>
9+
# 空一行
10+
[可选的正文]
11+
# 空一行
12+
[可选的脚注]
13+
14+
## 页眉设置
15+
16+
强制支持的类型名是`fix`和`feat`，同样支持`Angular`准则中推荐的其他类型
17+
18+
常规提交规范还推荐使用类型`improvement`，表示在不添加新功能或修复`bug`的情况下改进当前的实现
19+
20+
## 页尾设置
21+
22+
强制支持在页脚使用`BREAKING CHANGES`
23+
24+
## 提交规范
25+
26+
结合[RFC2019](https://www.ietf.org/rfc/rfc2119.txt)，在下面规范中使用关键字来指示需求级别
27+
28+
* `MUST`（必须）
29+
* `MUST NOT`（禁止）
30+
* `REQUIRED`（需要）
31+
* `SHALL`（应当）
32+
* `SHALL NOT`（不应当）
33+
* `SHOULD`（应该）
34+
* `SHOULD NOT`（不应该）
35+
* `RECOMMENDED`（推荐）
36+
* `MAY`（可以）
37+
* `OPTIONAL`（可选）
38+
39+
1. 每次提交**必须**添加类型名为前缀。类型名是一个名词，比如`feat、fix`，后跟冒号和一个空格
40+
2. 类型`feat`**必须**在提交新特征时使用
41+
3. 类型`fix`**必须**用于修复`bug`的提交
42+
4. 类型后面**可以**添加一个可选的作用域。作用域名是一个短语，表示代码库中的一个小节，比如`fix(parser)`
43+
5. 在类型/作用域前缀后面**必须**跟上一个简短描述，关于本次提交的代码修改，比如`fix: 字符串中包含多个空格时的数组分析问题`
44+
6. **可以**在描述后面添加一个长的正文，用于提供额外的上下文信息。正文内容**必须**在短描述后空一行开始
45+
7. **可以**在正文后空一行开始页脚，页脚**应该**包含这次代码修改的相关问题，比如`Fixes #13`
46+
8. 不兼容修改(`breaking change`)**必须**放置在提交的页脚或正文部分的最开始处，**必须**使用大写文本`BREAKING CHANGE`作为前缀，后跟冒号和一个空格
47+
9. 在`BREAKING CHANGE:`后面**必须**提供一个描述，关于`API`的修改，比如`BREAKING CHANGE: 环境变量目前优先于配置文件`
48+
10. 页脚**必须**包含不兼容修改、额外链接、问题引用和其他元信息
49+
11. 除了`feat`和`fix`以外的类型**可以**在提交信息中使用
50+
51+
## 徽章
52+
53+
使用了常规提交规范可以添加徽章在`README`
54+
55+
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
56+
57+
## 实现示例
58+
59+
只有页眉和页尾
60+
61+
feat: allow provided config object to extend other configs
62+
63+
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
64+
65+
只有页眉
66+
67+
docs: correct spelling of CHANGELOG
68+
69+
使用了作用域
70+
71+
feat(lang): added polish language
72+
73+
修复了`bug`
74+
75+
fix: minor typos in code
76+
77+
see the issue for details on the typos fixed
78+
79+
fixes issue #12
80+
81+
## `FAQ`
82+
83+
问：在最初开发阶段如何处理提交信息？
84+
85+
建议像已发布产品一样处理。即使是你的软件开发伙伴在使用软件过程中，也想知道那些被修复了，那些是不兼容修改。
86+
87+
问：提交头的类型名是大写还是小写？
88+
89+
无所谓，不过最好保持一致（一直大写或一直小写）
90+
91+
**问：如果提交内容适用于多个类型怎么办？**
92+
93+
尽可能返回并进行多次提交。常规提交准则的优势在于它有能力驱动我们进行更加组织化的提交和`PR`
94+
95+
问：这是否是不鼓励快速开发和快速迭代？
96+
97+
它不鼓励以无序的方式快速开发。它帮助你在有多个开发者的多个项目中进行长期开发
98+
99+
**问：常规提交准则是否会限制提交的类型?**
100+
101+
常规提交准则鼓励开发者使用更多有确切含义的类型。除此以外，准则的灵活性允许开发组提出更多适用于自己的类型，并随着时间的推移更改这些类型
102+
103+
问：这个准则和[SemVer](https://semver.org/lang/zh-CN/)的联系？
104+
105+
`fix`类型应该翻译成`PATCH`版本。`feat`类型应该翻译成`MINOR`版本。如果提交信息中包含`不兼容修改`，不管哪种类型，都应该翻译成`MAJOR`版本
106+
107+
问：如何将扩展版本转换为常规提交规范?
108+
109+
我们建议使用`SemVer`发布您自己对本规范的扩展（并鼓励您进行这些扩展！）
110+
111+
**问：如果我不小心使用了错误的提交类型，该怎么办？**
112+
113+
1. 使用了规范中的类型但是没有使用正确的类型，比如使用`fix`替代了`feat`
114+
115+
在合并或者发布这个错误之前，推荐使用`git rebase -i`进行提交历史编辑。发布之后，依据使用的工具或流程进行清理
116+
117+
2. 当使用了规范外的类型，比如使用了`feet`替代了`feat`
118+
119+
如果提交不符合常规提交规范，它只是意味着基于规范的工具将错过这次提交
120+
121+
**问：是否我的所有贡献者都需要使用常规提交规范?**
122+
123+
如果使用基于`squash`的`Git`工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。常见的工作流程是让`git`系统自动从`pull request`中`squash`出提交，并向主维护者提供一份表单，用以在合并时输入适合的`git`提交信息。

‎docs/message/gitmessage.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
2+
# [gitmessage]提交模板
3+
4+
## 默认模板
5+
6+
在提交时打开编译器，默认会出现一段模板信息，提示你编辑提交信息，同时会提示当前修改的文件
7+
8+
$ git commit
9+
10+
# Please enter the commit message for your changes. Lines starting
11+
# with '#' will be ignored, and an empty message aborts the commit.
12+
# On branch master
13+
# Your branch is ahead of 'origin/master' by 1 commit.
14+
# (use "git push" to publish your local commits)
15+
#
16+
# Changes to be committed:
17+
# modified: ...
18+
# deleted: ...
19+
#
20+
21+
## 自定义模板
22+
23+
可以自己编辑一个模板文件，比如新建`~/.gitmessage`，编辑一段关于提交规范的注释
24+
25+
$ vim ~/.gitmessage
26+
27+
# head: <type>(<scope>): <subject>
28+
# - type: feat, fix, docs, style, refactor, test, chore
29+
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
30+
# - subject: start with verb (such as 'change'), 50-character line
31+
#
32+
# body: 72-character wrapped. This should answer:
33+
# * Why was this change necessary?
34+
# * How does it address the problem?
35+
# * Are there any side effects?
36+
#
37+
# footer:
38+
# - Include a link to the ticket, if any.
39+
# - BREAKING CHANGE
40+
#
41+
42+
修改全局配置文件`~/.gitconfig`，添加
43+
44+
[commit]
45+
template = ~/.gitmessage
46+
47+
再次提交时显示的模板如下
48+
49+
# head: <type>(<scope>): <subject>
50+
# - type: feat, fix, docs, style, refactor, test, chore
51+
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
52+
# - subject: start with verb (such as 'change'), 50-character line
53+
#
54+
# body: 72-character wrapped. This should answer:
55+
# * Why was this change necessary?
56+
# * How does it address the problem?
57+
# * Are there any side effects?
58+
#
59+
# footer:
60+
# - Include a link to the ticket, if any.
61+
# - BREAKING CHANGE
62+
#
63+
64+
# Please enter the commit message for your changes. Lines starting
65+
# with '#' will be ignored, and an empty message aborts the commit.
66+
# On branch master
67+
# Your branch is ahead of 'all/master' by 2 commits.
68+
# (use "git push" to publish your local commits)
69+
#
70+
# Changes to be committed:
71+
# new file: .gitignore
72+
#
73+
# Untracked files:
74+
# package.json
75+
#
76+
77+
## 文件解析
78+
79+
在仓库内的`.git/COMMIT_EDITMSG`文件中保存了最近一次提交的日志（包括模板信息）
80+
81+
## 相关阅读
82+
83+
* [优雅的提交你的 Git Commit Message](https://zhuanlan.zhihu.com/p/34223150)

‎docs/message/index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
# 引言
3+
4+
每次进行`git`提交时，需要写提交说明，规范提交说明的好处如下
5+
6+
1. 更加结构化的提交历史
7+
2. 保证每次信息都有确切的含义
8+
3. 方便直接生成`changelog`
9+
4. 方便信息搜索和过滤
10+
11+
## 相关阅读
12+
13+
* [Commit message 和 Change log 编写指南](http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html)
14+
* [如何写好 Git commit log?](https://www.zhihu.com/question/21209619)
15+
* [优雅的提交你的 Git Commit Message](https://zhuanlan.zhihu.com/p/34223150)

0 commit comments

Comments
 (0)