Git Commit specification and CHANGELOG custom generation

preface

During daily project development and maintenance, some CHANGELOG may be manually maintained and updated. While this kind of manual log maintenance may make the content look cleaner, prettier, and more transparent, it also requires more resources. Also, in the case of multi-person development, the logs may not be synchronized with the Commit in real time, and it may not seem wise to stack the logs synchronously at release time. It may be a better choice to automatically generate CHANGELOG according to Commit. I have written an article about Git Commit specification, which is mainly about how to standardize Commit and automatically generate CHANGELOG. But the automatically generated CHANGELOG content isn’t pretty. Therefore, I want to take it one step further. I want to standardize the submission of code messages through automated commands, and I want to customize the CHANGELOG content style to make it look cleaner. That’s what this article is about: Git Commit specification and CHANGELOG custom generation.

Demo project address: github.com/niezicheng/…

Commitizen (Specification commit command line tool)

The installation

npm install -g commitizen
Copy the code

Git cz and VSCode are two ways to standardize git submission. Git-cz is recommended.

git-cz

You can use either of the following two methods: global installation or project, or both

Global installation

Install git-cz globally

npm install -g git-cz
Copy the code

After installation, directly replace git COMMIT information with Git Cz

git cz
Copy the code

Used in the project

Commitizen install and configure git-cz

commitizen init git-cz --save-dev --save-exact
Copy the code

The following content is automatically added to package.json after the above installation is complete

"devDependencies": {
  "git-cz": "^ 4.8.0"
},
"config": {
  "commitizen": {
    "path": "./node_modules/git-cz"}}Copy the code

You can also run the git cz command to replace the git commit after installing git-cz globally

cz
Copy the code

VSCode plug-in mode

1. VSCodeThe shop installedVisual Studio Code Commitizen SupportThe plug-in
2. command + shift + pThe inputconventional commit, they could havecommitizenThe effect of
3. Create a custom configuration file in the root directory.cz-config.jsTo add the corresponding configuration information. For details, seeDemo project address)(The effect is shown below)

Note ⚠️ : after modifying the contents of the.cz-config.js configuration file, VSCode may need to be restarted for the modification to take effect. Seems to be a bug in the plugin

standard-version

The installation

npm i --save-dev standard-version
Copy the code

The script command is configured in package.json based on the author’s daily practice. Run the NPM run release command. You can view the following common parameter descriptions or the official standard-version document.

"scripts": {
  "prerelease": "standard-version --release-as patch --dry-run".// Preview the CHANGELOG content
  "release": "standard-version --release-as patch" // Upgrade patch versions and generate or update CHANGELOG files
}
Copy the code

Global installation

npm i -g standard-version
Copy the code

After the global installation is complete, you can directly run the standard-version command on the terminal.

To avoid the default behavior of the standard-version command, the following example commands carry the –dry-run parameter to preview the results

Standard-version --release-as patch --dry-run // Preview the CHANGELOG content and configure the generated patch versionCopy the code

The default behavior

Standard-version --dry-run // PreviewCopy the code

The standard-version command does the following:

1. Caches current file changes
2. Rewind history to the last onegitLabel position (viewpackage.jsonTo locate the locationgitThe label)
3. Update version number (if not specified, update version according to default rules)
4. outputchangelogFile (customizable output content style)
5. Submit changes
6. Type in the new versiongit tag

Updating rules (default)

standard-version --dry-run
Copy the code

• featureAdvance updateminor
• bug fixWill updatepatch
• BREAKING CHANGESWill updatemajor

More version related knowledge content

Standard – version custom

• Custom outputCHANGELOGcontent
• The customstandard-versionAct of offering
• Custom updates the specified version number

CHANGELOG content customization

Custom configuration mode

1. inpackage.jsonConfiguration in the file
2. new.versionrcConfiguration file For configuration (the configuration file can be.versionrc..versionrc.json 或 .versionrc.js)

For more details, see the official standard-version document

The following uses building the. Versionrc configuration file as an example

The. Versionrc configuration file is created in the root directory. The. Versionrc content can be viewed as the demo project address

Versionrc // Create a. Versionrc configuration fileCopy the code

Run the NPM run prerelease command to preview the changelog content (if the corresponding script is configured in the previous installation content section). As shown below:

npm run prerelease
Copy the code

Standard-version Behavior customization

Standard-version default behavior can be customized (whether to skip the corresponding behavior)

• A:.versionrcConfiguration in file

{"skip": {"bump": true, // Cache changes and reset git state to the nearest tag node "changelog": true, // Automatically produce changelog document "commit": Git git git git git git git git git git git git git git gitCopy the code

• Method 2: CLI configuration

You can configure the parameters in the form of command parameters. For details, see common parameter description –skip

standard-version --skip.changelog false
Copy the code

Release customization

You can configure the parameters in the command format. For details, see —-release-as

Common Parameters

— Dry-run (Content preview)

Preview the effect of the CHANGELOG content after the command is executed

standard-version --release-as patch --dry-run
Copy the code

–release-as (specify release)

Manually control the version of the standard-version command

Standard version - release - as [option | specific version number]Copy the code

Main option

Major: [2.0.0] Minor: [1.1.0] patch: [1.0.1]Copy the code

More version knowledge content

Example:

Standard-version --release-as patch // Upgrade patch type Version standard-version --release-as 6.6.6 // Forcibly upgrade the static version to standard-version --first-release // first-release will not update the version numberCopy the code

— Prerelease

NPX standard-version -- --prerelease version changes from 1.0.0 to 1.0.0-0 NPX standard-version -- --prerelease alpha version changes from 1.0.0 to 1.0.0 1.0.0 - alpha. 0Copy the code

— Skip (Behavior Control)

Whether to skip a default behavior of the standard-version command

standard-version --skip.[option] [false/true]
Copy the code

Main option

The bump cache changes and resets git status to the nearest tag node changelog Automatically generates the Changelog document. Commit Commits the change tag to add a tag to GitCopy the code

Commitlint & Husky (Commitlint message validation)

• commitlint: used to check submitted information;
• husky 是 hookTool, operating on phigit-commit 和 git-pushphase

Depend on the installation

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

Configuration information

Commitlint configuration

Create a new commitlint.config.js configuration file in the root directory, or in package.json (either)

Commitlint. Config. Js file

rulesYou can also use the default without addingrulesconfiguration

More rules configuration information

module.exports = {
  extends: ['@commitlint/config-conventional'].rules: {
    'body-leading-blank': [2.'always'].// Body begins on a blank line
    'header-max-length': [2.'always'.72].// Header contains a maximum of 72 characters
    'subject-full-stop': [0.'never'].// subject does not end with '.'
    'type-empty': [2.'never'].// type is not empty
    'type-enum': [2.'always'['feat'.// New features, requirements
      'fix'./ / bug fixes
      'docs'.// Document content changed
      'style'.// Changes that do not affect the meaning of the code, such as removing Spaces, changing indentation, adding and removing semicolons
      'refactor'.// Code refactoring
      'test'.// Add or modify tests
      'chore'.// Do not modify other changes to SRC or test, such as changes to the build process or accessibility tools
      'revert'.// Execute git revert printed message]],}};Copy the code

Package. The json file

{  
  "commitlint": {
    "extends": ["@commitlint/config-conventional"]}}Copy the code

Husky configuration

The oldhuskyConfiguration, I tried it and it seems to have no effect, you can use the new configuration below

Package. The json file

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"}}}Copy the code

The newhuskyconfiguration

Active Hooks

Executing the following command generates a.husky folder

npx husky install
Copy the code

Add Hooks

Add content to the.husky file

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'
Copy the code

The code submission is not in accordance with the configuration specification, as shown below:

The git cz file can be configured using the git CZ file. The git CZ file can be configured using the git CZ file

The final effect of the CHANGELOG file content is as follows:

Git Commit (Conventional Commit) Standard-version Official documentation Git-CZ Official documentation Automatic output of Changelog – Section 1: Specification submission code automatic output of Changelog – Section 2: Automatically generate COMMIT specifications and generate Changelog