preface

The latest idea is to use vue3+ TS to write a poem reciting H5 (to satisfy my poetry reciting habit). To do a good job, he must sharpen his tools. Put up a shelf first! Although it is a person to write their own project, but the development specifications should also have oh! When making the commit specification and automatically generating the changlog, I got a lot of trouble because I wanted to commit the emotical-beginning commit format!! So write this article to commemorate ~ oh! No ~ is to summarize the summary to share with all the people around want to step on the pit son ~ ok! No more nonsense, officially began my performance ~😝

Commit Specifications

First of all, canonical commit information makes it clear at a glance what type of commit it is, the scope of the change, and the specific change, improving team collaboration. It is also convenient for us to find bugs in the future and improve teamwork.

Let’s take a look at some of the most commonly used Angular team specifications.

Angluar Commit Message specification

The specification divides commit information into header, body, and footer sections.

None of these three lines should be more than 100 characters long! (From the Angular specification documentation)

Here’s why you want to limit the character length, because Git will truncate the subject portion of the commit to more than 72 characters. The effect is shown in the following example:

The format of the Angluar commit message is as follows:

<type>(<scope>): <subject> // This is Header <BLANK LINE> <body> <BLANK LINE> <footer>Copy the code

The Body part is relatively simple. It is optional and refers to the specific description of this submission.

The Header section

The specification divides the header into three parts: Type, scope and Subject.

type

Type indicates the submission type. The value must be one of the following:

  • Feat: A new feature
  • Fix: An error fix
  • Docs: Only documents are changed
  • Style: Changes that do not affect the meaning of code (whitespace, formatting, missing semicolons, etc.)
  • Refactor: Code changes that neither fix bugs nor add functionality (refactoring)
  • Perf: Code changes that improve performance
  • Test: Adds missing or corrects existing tests
  • Build: Changes that affect the build system or external dependencies (gulp, NPM, etc.)
  • Ci: Changes to CI profiles and scripts
  • Chore: Changes the build process or helper tools and libraries, such as document generation

scope

Scope refers to the scope of impact of this commit. It is optional and can be anything that specifies the location of the commit change. I usually write the module name or file name of the changed part.

You can use an asterisk (*) when the change affects more than one scope. You don’t have to.

subject

Subject refers to the brief description of this submission, which has the following two rules.

  • Don’t capitalize the first letter
  • There is no dot at the end (.)

The Footer section can contain either of the following

  • Whether any destructive changes were made

If the current code is incompatible with the previous version, such as version upgrade, interface parameter reduction, interface deletion, migration, etc., it is a destructive change.

For destructive changes, the Footer section begins with BREAKING CHANGE, followed by a description of the CHANGE, the reason for the CHANGE, and the migration method. As follows:

BREAKING CHANGE: Description of CHANGE, reason, method of migrationCopy the code
  • Close the Issue

If the current commit is for an issue, you can close that issue in the Footer section, or you can close multiple issues. Fill in the following format:

Close #ISSUE_ID
Closes #ISSUE_ID, #ISSUE_ID
Copy the code

If you use jIRA, you can also enter the JIRA_ID affected by this change, but to enable this function you need to integrate JIRA with GitLab and JIRA with Github. Fill in the following format:

Re #JIRA_ID // re means fix #JIRA_IDCopy the code

Commit to Git in the following format:

This is the Angular team commit specification. You can customize the commit specification to suit your team’s preferences.

Customize the COMMIT Message specification

This part I will introduce to you, I want to customize the submission format in this project, you can learn from.

I think the custom spec is based on the Angluar spec, just add an emoticon gitmoji field at the top of it. The format is as follows:

Gitmoji: <type>(<scope>): <subject> // This LINE is Header <BLANK LINE> <body> <BLANK LINE> <footer>Copy the code

The gitmoji entry is mandatory and the value can only be the expression in the list of expressions provided by Gitmoji.

I will submit it to Git in the format I want:

Git-cz, which is displayed at the beginning of subject, is not consistent with the effect I want 😀, it looks like this drop!

So far, the commit specification format is pretty much covered! There are so many messy rules, of course, we can’t let the handwriting! 🎉🎉🎉🎉 Dang Dang dang ~ let’s use tools to play!

Commit specification tool

Here, we’ll talk about how to implement the Angluar default specification with the tools first, and then the custom ones. For both Angluar and custom we will need the following tool:

Commitizen: This will provide git cz instead of git commit to make it easier to generate compliant git commit messages.

Angluar specification version

Global installation

npm install -g commitizen
Copy the code

Initialize the Commitizen preset. cZ-Conventional – Changelog is used

Cz-conventional – Changelog: It is the preferred adapter for Commitizen. It has a default configuration, but you can also customize types and set properties such as header length. However, its prompt messages are in English and cannot be customized (found in the source code). If you need to customize the configuration prompt to use the CZ-Customizable adapter, which is available later in this article, click here to send it.

commitizen init cz-conventional-changelog --save-dev --save-exact
Copy the code

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

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

Git cz or cz can now be used to commit a commit.

Instead of git commit, you can run git cz or cz in any git init directory.

In-project installation

npm install commitizen cz-conventional-changelog -D
Copy the code

In package.json, here is the Adapter that sets CZ-Xconventional – Changelog to Commitizen. You can also choose other adapters. The custom version of this article has other Adapter Settings by clicking here.

"scripts": {
  "commit": "cz"
}
"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}
Copy the code

Git commit can only be replaced by NPM run commit in the current project directory.

For the convenience of using cz command, both global and project are installed, below demonstrate the effect:

At this point, you have automated the COMMIT. However, CZ-Xconventional Changelog does not support facial expressions. Let’s talk about how to add facial expressions.

The expression displayed at the beginning of the subject section

The expression at the beginning of the subject section can also be without expression. The submission effect is as follows:

To achieve this effect, use streamich/ Git-cz

1. Global installation

If commitizen is already installed, the git cz command will override the effect of commitizen git cz.

npm install -g git-cz

git-cz
Copy the code

2. Use with commitizen projects

npm install -D git-cz
Copy the code

The adapter for Commitizen in package.json is git-cz:

{
  "config": {
    "commitizen": {
      "path": "git-cz"
    }
  }
}
Copy the code

Run the following command

npx git-cz
Copy the code

The commit has an expression at the beginning of the subject:

😭 my computer expression shows garbled code, has not been solved (there are friends who know how to solve the trouble evaluation area told me, I really can not make out 😰), but only on the computer garbled code display, to github to see is normal display, so it will not obstruct my submission, just look at the in the mind.

There is a small problem here. In actual operation, I found that as long as you install git-cz, you can run the NPX git-cz command, and the displayed selection text is also consistent with the default Settings of git-cz. There is no need to set the package.json configurator. I do not know why it is inconsistent with the official website description. I have not figured out 😥.

The Git-cz tool also provides custom configurations, but the configuration items are limited. Add changelog.config.js to the root directory. Here is an example of an official configuration for streamich/git-cz.

./changelog.config.js module.exports = { "disableEmoji": false, "list": [ "test", "feat", "fix", "chore", "docs", "refactor", "style", "ci", "perf" ], "maxMessageLength": 64, "minMessageLength": 3, "questions": [ "type", "scope", "subject", "body", "breaking", "issues", "lerna" ], "scopes": [], "types": { "chore": {"description": "Build process or auxiliary tool changes", "emoji": "🤖", "Chore"}, "ci" : {" description ":" ci related changes ", "emoji" : "🎡", "value" : "ci"}, "docs" : {" description ": "Documentation only changes", "emoji": "✏️", "value": "docs"}, "feat": {"description": "A new feature", "emoji": "🎸", "value" : "feat"}, "fix" : {" description ":" A bug fix, "" emoji" : "🐛", "value" : "fix"}, "perf" : {" description ": "A code change that improves performance", "emoji": "⚡️", "value": "perf"}, "refactor": {"description": "A code change that neither fixes A bug or adds A feature", "emoji": "💡", "value": "refactor"}, "release": {"description": "Create a release commit", "emoji": "🏹", "value": "release"}, "style": {"description": "Markup, white-space, formatting, missing semi-colons..." , "emoji" : "💄", "value" : "style"}, "test" : {" description ":" Adding missing tests ", "emoji" : "💍", "value" : "test" } } }Copy the code

This type of COMMIT does not need to add an additional tool for mandatory verification of commit. Since the expression belongs to the Subject field, this format conforms to Angluar specification, and verification with Angluar can be passed by default. So some people want to commit with commitizen+git-cz.

Emoticons appear at the top of the submission

Here, I’ll introduce an adaptor, CZ-Emoji, recommended by Commitizen, but I’m not talking about it. It commits the following commit information:

Cz-emoji: This adaptor replaces the type part with emoji. Because this one is relatively simple, it’s interesting to go to the description on the website, and I won’t talk about how to use this one.

Well, here is mainly about how to add the expression on the basis of Angluar, retain the situation of type, add the expression in front of type :emoji: (this is my own made a long time 😂). The COMMIT specification is the expression opening specification I mentioned above

Go ahead, let’s install CZ-Customizable first

npm i -D cz-customizable
Copy the code

package.json

"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}
Copy the code

Cz-customizable: This is the adaptor for customizing cZ commands, you can customize the prompt, types, length, and so on.

Js in the root directory of the project to add the configuration item, you can refer to the official website to configure the prompts and rules of your own project, my configuration file is as follows:

/. Cz-config.js module. Exports = {types: [{value: 'feat', name: 'feat'}, {value: 'fix', name: 'fix: ' Fix bug'}, {value: 'init', name: 'init: initialization '}, {value: ':pencil2: docs', name: 'docs: document changes'}, {value: }, {value: 'refactor', name: 'refactor: refactor'}, {value: 'perf', name: 'perf: ' Performance optimization '}, {value: 'test', name: 'test: test'}, {value: 'revert', name: 'revert: '}, {value: 'build', name: 'build: Package '}, {value: 'chore', name: 'chore: Build/project dependency/tool '}, {value: 'ci', name: 'CI: ci related changes'}], messages: {type: 'Please select submission type (required)', customScope:' Please enter file modification scope (optional)', Subject: 'Please briefly describe submission (required)', Body:' Please enter detailed description (optional)', breaking: 'List any BREAKING CHANGES(optional)', footer:' Enter issue to close (optional)', confirmCommit: 'Are you sure to submit this description? '}, allowCustomScopes: true, allowBreakingChanges: ['feat', 'fix'], // The destructive modification option will only be subject if the submission type is feat or fix;Copy the code

Now type cz or git cz to look like this:

Since I wanted to start with an expression, I used a trick to change the types field of.cz-config.js to look like this:

Types: [{value: ': zap: feat', name: '⚡ feat: new features'},...Copy the code

The effect is as follows, which is to add the emoticon part, the other effect is the same as the above, do not record GIF:

Zap: ⚡ is not used because we need to add verification commit information later. The default of verification expression is that only the verification code can pass. This format is not in accordance with Angluar specification as we have defined it, so we need to install other verification tools. Almost there!

The expressions here are all usedgitmojiThe emoticons provided in this section, and the emoticons followed by the mandatory validation commit message are also emoticons that verify whether they are included in this section. The emoji will still be displayed on the command line, but will be displayed when submitted to Github. The diagram below:

Vscode submission tool

If you are too lazy to type the command to commit, here are two plug-ins that I personally think are ok. Just search the extension store and install them. The Usage is very simple, but you can read the Usage when downloading. (later I will write a vscode plug-in that conforms to my own commit habit, and recommend it to you then) 😁

Visual Studio Code Commitizen SupportThis plugin is what I’ve always been used to. It follows cz-customizable and creates the required configuration file. If your project root directory has.cz-config.js configuration, it will display the prompts and validation rules based on this configuration file (you need to reboot vscode to take effect). This plug-in submission looks like this:

Conventional CommitsThis plugin allows you to fill in emoticons (optional) in the angluar or Angluar + Subject plus emoticons format. This plug-in submission looks like this:

Standard calibration

The above mentioned code tools, although you can make it convenient to mention the code, but! What if someone on your team just doesn’t follow the code? It’s time for the Husky Commitlint! They can verify that your commit information is canonical at commit time, and if it isn’t, it won’t commit.

This part is also divided into Angluar version and custom emoticon version. First of all, no matter the description version, you need to install these two tools:

Husky: As the name suggests, husky, ha ha, bite you in the teeth. Git hook – This tool is used to run commands in git hooks. It is used to execute eslint, run test, and commitlint commands.

Commitlint: This is a commitlint that validates your commit information, providing multiple shared configurations.

A Commit message check

First, download Husky & CommitLint.

npm i -D husky commitlint
Copy the code

Create a new.commitlintrc.js or commitlint.config.js. Commitlint will find this file and verify the COMMIT information according to the extends specified in the file. You can also customize some rules.

Angluar version

Verify the angluar COMMIT specification as follows:

/.commitlintrc.js

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

@commitlint/ config-Conventional is certified to angluar, you can also use other versions, or write your own version of Lint and send it to NPM.

Open the front page emoji

Commitlint does not have an appropriate shareable configuration built into it. Fortunately, there is a shareable configuration already written by commitLint. Here I’m using commitlint-config-Gitmoji written by the Big Guy of Empty Valley, which I found online.

npm i -D commitlint-config-gitmoji
Copy the code

As follows:

/.commitlintrc.js

module.exports = {
  extends: ['gitmoji']
};
Copy the code

With commitLint set, we’ll implement commitLint mandatory validation.

Husky forces the commit information to be validated

Executing the following command will generate a.kusky folder in the project root directory. (Husky is the latest version 5.0.)

npx husky install
Copy the code

Create a commit-msg file in the.kusky folder with the following contents:

#! /bin/sh npx --no-install commitlint --edit "$1"Copy the code

If the commit message does not comply with the specification, commitLint will inform us of a rule error, and Husky will block the current commit message. You can enforce compliance with the defined COMMIT specification.

Now, let’s talk about validating code and running tests before commit.

Code specification verification & run tests

Although our editors have the esLint plugin to fix code automatically, we generally do not commit code that does not conform to ESLint. However, some students may not install the plugin, do not fix it automatically, and write code blindly, so they need to verify the code specification and test before committing, just in case. In this way to ensure that the code you mention is serious in accordance with the specification and passed the test 🤣, ha ha ha!!

Lint-run Lint first, we need to have lint-staged installation. Many people don’t just have lint-staged execution of NPM Run Lint in pre-commit hooks. The problem with this is that if your project is large and you only modify one file, it will still validate all files from SRC. It will lead to the slow waiting for a code. Lint-staged versions solve this problem by validating only the parts of the file you have modified. All right, let’s get started

npm i -D lint-staged
Copy the code

package.json

"scripts": {
  "lint": "vue-cli-service lint --fix",
  "test": "your-cmd" 
},
"lint-staged": {
  "src/**/*.scss": [
    "stylelint --fix"
  ],
  "src/**/*.{js,vue,ts,tsx}": "npm run lint"
}
Copy the code

Create a pre-commit file in the. Kusky folder with the following contents:

#! /bin/sh npx --no-install lint-staged npm run testCopy the code

Here, when you submit code, it automatically validates and fixes your submitted code. Next, we begin to talk about CHANGELOG automatic generation.

CHANGELOG is automatically generated

CHANGELOG looks like this:

First, what is CHANGELOG and why is it needed? It records all the commit information of your project, categorizes the version, quickly jumps to that commit record, and even shows the creator who changed the person information at a glance to find the bug 😂. It makes it easy to know which version of a project does what and what bugs, etc. Also convenient to check the bug, for the submission of records at a glance, not one to turn over to check.

Here, use standard-version to automatically generate CHANGELOG. We will not talk about the conventional changelog, after all, it recommended us to use standard-version (this is the thing of the same team, based on the Conventional Changelog). Read the official explanation for why standard-version is recommended. Official address for everyone.

I won’t talk about seman-release either, because I haven’t done much research on CI/CD, so I can’t talk about 😂! The official address is here, and there is a recommended article that you can read if you are interested.

Ok, let’s start with standard-version! First, download ~

npm i -D standard-version
Copy the code

package.json

{
  "scripts": {
    "release": "standard-version"
  }
}

Copy the code

Run the following command to automatically generate the Changelog.md file based on your commit information.

npm run release
Copy the code

Run this command when your commit Type is feat and fix, and it will increment the version number.

If you delete the Changelog. md file after executing it once, and do not modify the commit, then execute the build command again, it will generate a file with only one version number. You must commit the file before executing the commit. However, those records before this commit are no longer displayed (oddly, watch out for this when debugging).

Versionrc.js file is created in the root directory. Here is an example of my versionrc.js content:

Module. Exports = {" types ": [{" type" : "feat", "section" : "✨ the Features | new feature"}, {" type ":" fix ", "section" : "🐛 Bug Fixes | Bug Fixes"}, {" type ":" init ", "section" : "🎉 init | initialization"}, {" type ":" docs ", "section" : "✏ ️ Documentation | document"}, {" type ":" style ", "section" : "💄 Styles | style"}, {" type ":" refactor ", "section" : "♻ ️ Code Refactoring | Code Refactoring"}, {" type ":" perf ", "section" : "⚡ Performance Improvements | Performance optimization"}, {" type ": "Test", "section", "✅ Tests | testing"}, {" type ":" revert ", "section" : "⏪ revert | back"}, {" type ":" build ", "section" : "📦 Build System | pack to Build"}, {" type ":" chore ", "section" : "🚀 chore | Build/project/tool to"}, {" type ":" ci ", "section" : "👷 Continuous Integration | CI configuration"}}]Copy the code

After configuration, my CHANGELOG looks like this!

It should be mentioned that the default default for standard-version is Angular. Commmit, unlike Angular, cannot categorize the change log generated without reading the corresponding type. The commitlint-config-gitmoji tool is set to “emoji: type:… Format generate CHANGELOG tool conventional- Changelog-gitmoji-config, here we directly use it! But this tool does not provide a custom configuration type copy function, writing in the source code is dead, so use the tools do not like the one above versionrc. Js custom, but it’s own also look good, you can set the display expression, also supports both Chinese and English, also supports the display and modifier mailbox, also is very powerful!!!!!! 🉑

Come on, let’s download ~ first

npm i -D conventional-changelog-gitmoji-config
Copy the code

Standard-version specifies another preset via the –preset command (found in source)

{
  "scripts": {
    "release": "standard-version --preset gitmoji-config"
  }
}
Copy the code

— Preset gitmoji-config is available for reading the preset, which is called Conventional – Changelog-gitmoji-config. This is because the conventional- changelog-loader looks for the conventional-changelog-xxx, and the prefix is written dead conventional-changelog-.

CI/CD is not used, and standard-version is not used. For convenience, I will execute the command to generate CHANGELOG directly in the pre-push hook

.husky/pre-push

#! /bin/sh npm run releaseCopy the code

In this way, when I do git push, the changelog. md will be automatically generated and submitted to the remote end, so there is no need to manually execute the NPM run release command to push. La la la 🎈 🎈 🎈

It’s finally over! Thank you for listening to me so long, I hope to help you, if there are mistakes in the article also hope to correct. Thank you!! 😜

reference

Angular official COMIT specification

Baidu to the unknown Mr. Empty language finch article

Gracefully Commit your Git Commit Message

A Friend’s Blog

As well as the documents and source code of each tool, not a list