Git contractual submission

Posted by markjia on Mon, 03 Jan 2022 09:04:25 +0100

summary

Every time we submit the code, we need to add a description for the content of this modification, for example:

git commit -m "Initial commit";
git commit -m "Fixed some known issues.";
git commit -m "Added new features.";

But in fact, some commit message s are strange, such as the following:

A commit should accurately describe the purpose and modification of this submission, such as:

git commit -m "chore: upgrade org.bouncycastle:bcprov-jdk15on from 1.69 to 1.70";
git commit -m "perf: optimize the code on global zookeeper";
git commit -m "docs(readme): fix typo";

This writing method comes from the Git contractual submission of the Angular team. You can read their specifications from the following link:

Use contractual submission

Contractual submission specifies the format of the commit message, as shown below:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LIKE>
<footer>

The submission message consists of header, body and footer. Let's introduce them in detail.

Message header

The header consists of type, scope and subject. In the complete contractual submission format, it occupies the following parts:

<type>(<scope>): <subject>

Means:

Type: required, the type of this submission.
Scope: optional, indicating the scope of this submission.
subject: required, a brief description of this submission.
type
The value of type must be one of the following lists:
build/chore 👷‍♀️: Changes used to build systems (including scripts, configurations, or tools) and dependencies.
ci: used for configuration files, script files, configurations or tools related to system continuous integration and continuous deployment.
docs 📝: Identifies changes to project related documents.
feat ✨: Used to identify new features.
fix 🐛: Used to identify bug fixes.
perf ⚡ Key: used to identify performance improvements.
refactor: used to identify code refactoring, which neither adds new functions nor fixes errors -- such as deleting redundant code, simplifying code, renaming variables, etc.
Style: used to mark code formatting, code style modulation, repair checkstyle and other problems.
tets: used to mark test related changes, modify existing tests or add new tests.
revert: user branch rollback.
Illustrate with a diagram:

scope

scope can be divided according to modules and packages. The specific use can be based on the specifications formulated by the team, such as:

git commit -m "feat(logger): support JSONL log output format";
git commit -m "feat(dao): add global controller excepiton handler";
git commit -m "feat(api): add reqeust interceptor"

subject

For a brief description of this submission, there are the following guidelines:

Initial lowercase.
Do not end with a period.

Example

The header is only the first line of the commit message. You can use git commit -m to complete this submission, for example:

git commit -m "chore(pom.xml): upgrade jackson-databind from 2.10.1 to 2.11.4"

In the above example, the submitted type is choice, and then the scope of influence is specified in the middle of (), or the modified file is POM XML, followed by an English: and a space is our subject. It should be noted that: it is in English, and a space and subject are required after: as the segmentation.

As mentioned earlier, scope is optional. If we ignore scope, the above example can be changed to:

git commit -m "chore: upgrade jackson-databind from 2.10.1 to 2.11.4"

Message body

body is optional. You can introduce the reason for modification and details:

fix(users): remove getFriends API endpoint

In accordance with new privacy policy, remove the getFriends API endpoint. 
(The endpoint will continue to exist for a while and return a deprecation notice)

It should be noted that there should be a blank line before the header and body.

Message footer

Footer is also optional. If the issue is modified in this submission, the issue can be referenced in the footer, for example:

fix(users): remove getFriends API endpoint

In accordance with new privacy policy, remove the getFriends API endpoint. 
(The endpoint will continue to exist for a while and return a deprecation notice)

Implements #2105

A blank line is also required between footer and body.

Benefits

Generate changelog

Browse records

We can browse the submission records of the specified type, such as the submission records of feat, fix and perf:

git log --oneline --grep "^feat|^fix|^perf"

commit message emoji

Adding emoji to the commit message will make our submission more interesting and easy to browse, for example:

You can find the emoji corresponding to the commit message type in the following link:

If you use the VS Code Editor or the package manager is npm, you can also find the corresponding plug-in:

Topics: git

Programmer Think