Git is the most popular version control tool on the market, and a well-written Commit message can greatly improve the efficiency of code maintenance. However, in daily development, the lack of constraints on commit messages leads to random filling, uneven quality, low readability, and difficult maintenance. It is imperative to introduce the Commit Message specification into your project.

With what specification?

One popular approach is Conventional Commits, which are inspired by, and largely based on, Angular Commits. The contracted commit specification is a lightweight convention based on commit messages. It provides a set of simple rules for creating a clear commit history; This makes it easier to write standards-based automation tools. This convention dovetails with SemVer, describing new features, bug fixes, and disruptive changes in the commit message. Its message format is as follows:

< type >[Optional scope]: < Description >[Optional text] [Optional footnote]Copy the code

Quick Start

1. Install commitizen and CZ-Conventional – Changelog globally

Commitizen is a tool for writing qualified commit messages in place of Git commit instructions, while the CZ-Xcom – Changelog adapter provides the Xcom – Changelog standard. Different adapters can also be used based on different requirements.

npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
Copy the code

Once installed, you can use git Cz instead of git commit.

In global mode, the ~/.czrc configuration file is required to specify Adapter for Commitizen.

2. Install CommitLint & Husky on the project

Commitlint is responsible for formatting commit messages, and Husky is responsible for providing git hooks that are easier to use.

Use npm

npm i -D husky @commitlint/config-conventional @commitlint/cli
Copy the code

Use yarn

yarn add husky @commitlint/config-conventional @commitlint/cli -D
Copy the code

Commitlint can only do formatting specifications, not content. Control of content quality is up to us.

3. Add related configurations

Create commitlint. Config. Js

# In the same path as package.json

echo 'module.exports = {extends: ["@commitlint/config-conventional"]}; ' > ./commitlint.config.js
Copy the code

The introduction of husky

# package.json. ."husky": {
    "hooks": {
      "commit-msg": "commitlint -e $GIT_PARAMS"}}Copy the code

Use 4.

Run git Cz to enter interactive mode and enter the interactive mode as prompted

1.Select the type of change that you're research type (
      
       ) 2.What is the scope of this change (e.g. component or file name)? 3.Write a short, imperative tense description of the change: 4.Provide a longer description of the change: (Press enter to skip) Write a long description of the changes (). Is (y/ N) a destructive modification? Default n (
       

        ) 6.Does this change affect any openreve issues? What problem did the (y/n) change fix? The default n (< footer >)
       

      Copy the code

The format of the generated COMMIT message is as follows:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Copy the code

After filling in the message, Husky calls commitLint to format the message. By default, type and subject are mandatory.

Any option of the Git commit directive can be used with the Git Cz directive, such as git cz-a

Commit Message specification usage in RRD-FE landing

Based on the team’s current usage, we discussed the rules for filling in each part of the Commit Message.

1. type

Type is mandatory. It is used to specify the commit type. Feat and fix are mandatory, and docs, style, build, refactor, and Revert are mandatory.

# main typeFeat. Fix a bug# special typeStyle: changes that do not affect the meaning of the code, such as removing whitespace, changing indentation, adding or deleting semicolons. Build: changes that are made to the builder or external dependencies, such as webpack, NPM refactor: changes that use revert when refactoring. Do git revert to print the message# do not use type
test: Adds tests or modifies existing tests PERF: Changes to improve performance CI: Changes to chore related to CI: does not modify SRC ortestRemaining modifications, such as changes to the build process or accessibility toolsCopy the code

When a change includes both the main type and the special type, the main type is used.

2. scope

Scope is also mandatory, which describes the scope of change. The format is project name/module name, for example, Node-PC/Common RRD-h5 / Activity. We-sdk does not need to specify module name. If multiple modules are modified at one commit, it is recommended to split them into multiple COMMIT for better tracking and maintenance.

3. body

Fill in the detailed description of body, mainly describing the situation before the change and the motivation for the change. There is no requirement for small changes, but the body must be added to explain major needs and updates.

4. break changes

Break changes Specifies whether break changes occur. This parameter must be specified when changes involving break changes occur, such as version upgrade, interface parameter reduction, interface deletion, and interface migration.

5. affect issues

Affect Issues Indicates whether an issue is affected. For example, when we use JIRA, we can fill in the JIRA_ID of its influence in the Commit message. To enable this function, we need to connect jIRA and Gitlab first. Reference: docs.gitlab.com/ee/user/pro…

For example:

re #JIRA_ID
fix #JIRA_ID
Copy the code

The sample

  • The complete commit Message example
  • Corresponding Git log

Finally, welcome to star our renrendai big front-end team blog. All the articles will be updated to zhihu column and Nuggets account simultaneously. We will share several high quality big front-end technology articles every week. If you like this article, please give it a thumbs-up.

Further reading

Conventional commits must read the submission standard of description.

The Angular specification reads what to write and how to write each part of the Angular standard.

@commitlint/config-conventional Read this section describes the commitlint config-Conventional check rule and passes/fails situations.