1. Background
Today's software development is often a collaborative project that requires multiple people to participate. When the project is on track, subsequent developers often need to submit some code to add new features or fix bugs. As the project continues to develop and iterate, the content will continue to change. We gradually forget the changes in the project. At this time, the project needs to maintain a change log to coordinate everyone at the same pace.
2. The status quo
At present, many company development projects do not follow a good specification. After developing part of the project, different developers submit code, and often define their own commit message according to their own style. The submission is more casual than the following picture, which makes it difficult understanding. When there is a bug in the code, it is not clear which version to roll back to.
In this regard, related organizations have proposed a plan to mark and submit commit messages. Among them, Keep a Change Log[1] and AngularJS[2] both use their own specifications. The AngularJS specification is a set of message specification submission standards launched by Google, which is currently the most widely used writing method. Therefore, this sharing focuses on the AngularJS message submission specification. The commit message after using the AngularJS submission specification is shown in the figure below.
3. Goal
a. 在浏览的时候可以提供更好的历史信息
For example, through the following command, you can display the changes after the last release. Just look at the beginning of each commit to know the purpose of the commit
git log HEAD --pretty=format:%s
b. 允许通过命令过滤掉某些提交信息
git log HEAD --grep feat ----View the newly added features:
git log HEAD --grep fix ----View the fixed bugs:
c.允许通过脚本自动生成日志
4. The format of the commit message
<type>(<scope>): <subject> ---Header部分
<BLANK LINE> ---空一行
<body>
<BLANK LINE> ---空一行
<footer>
<type> (required):
• feat: add new features
• fix: fix bugs
• docs: only modify the document
• style: only modify the spaces, format indentation, etc., without changing the code logic
• refactor: code reconstruction, no new features Or fix bugs
• test: add test cases
• chore: change the build process, or add dependent libraries, tools, etc.
• revert: roll back to the previous version
<scope> (optional):
The scope of the modified project can be specified by oneself (use * when no suitable scope is used).
<subject> (required):
A short title that highlights the content of the submission. The English is in the present tense, the first letter is not capitalized, and the end is not punctuated.
<body> (optional)
Describe the specific modification content, in English in general present tense, such as
- Modified content 1
- Modified content 2
- Modified content 3
<footer> (optional)
Applicable to two situations:
a. Incompatible changes
If the current code is not compatible with the previous version, the Footer part starts with BREAKING CHANGE, followed by a description of the change, the reason for the change, and the migration method.
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.
b. Close Issue
Such as:
Closes#123
or:
Closes #123, #234, #345
<BLANK LINE>
Blank line
Note:
1. In order to avoid line
breaks when reading, each line generally does not exceed 100 characters; 2. Revert: There is also a special case, if the current commit is used to revoke the previous commit, it must start with revert: , Followed by the Header of the revoked Commit.
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
Body部分的格式是固定的，必须写成This reverts commit <hash>.，其中的hash是被撤销 commit 的 SHA 标识符。
5. Use tool
5.1 Commitizen (https://github.com/commitizen/cz-cli)
Mac computer needs to install npm first,
$ brew install npm
$ npm install -g commitizen
$ commitizen init cz-conventional-changelog --save-dev --save-exact
Use git cz instead of git commit
5.2 validate-commit-msg( https://github.com/conventional-changelog-archived-repos/validate-commit-msg )
Verification format tool, installation command
$ npm install --save-dev validate-commit-msg
The verification rules can be configured by editing the file
5.3 Conventional-changelog (https://github.com/conventional-changelog/conventional-changelog)
run command
$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0
自动生成日志
5.4 IDEA plug-in Git Commit Template
6. Summary:
[1] https://keepachangelog.com/
[2] https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.uyo6cb12dt6w