Hello everyone, my name is Luozhu 🎋, a wooden front end in Hangzhou, 🧚🏻♀️. If you like my article 📚, please click “like” to help me gather “jinli”.

The best practices in this article have been written as a CLI tool and can be obtained by NPM install -g@youngjuning /cli and executing youngjuning init-commitlint

preface

Normalized Git Commit plays an important role in improving git log readability, controllable version control and Changelog generation. However, it was not only the promotion of the team that hindered our steps, but also the configuration of a series of tools. Commitlint and CommItizen work together and customize the commit specification. This article summarizes current best practices for you. If it helps, a star is enough.

Conventional Commits a specification

Conventional Commits are specifications used to add readable meaning to submitted messages. The contractual submission specification is a lightweight message-based convention. It provides a simple set of rules for creating a clear commit history; This makes it easier to write automation tools based on specifications. This convention is consistent with SemVer, describing new features, bug fixes, and destructive changes in the commit message.

The structure of the submission note is as follows:

< Type >([optional scope]): < description > [optional text] [optional footnote]Copy the code

(Type)

  • feat:: the type offeatThe commit represents a new feature in the code base (this is the same as in the semantic versionMINOR).
  • fix:: the type offixThe commit indicates that a bug has been fixed in the code base (this is the same as in the semantic versionPATCH).
  • docs:: Just changes the document.
  • style:: Does not affect changes in code meaning (whitespace, formatting, missing semicolon, etc.)
  • refactor:: Code refactoring without fixing bugs or adding functionality.
  • perf:: Code changes to improve performance.
  • test:: Add actual tests or correct existing tests.
  • build:: Changes that affect the build system or external dependencies (sample scope: GULp, Broccoli, NPM).
  • ci:: Change continuous integration files and scripts (sample scope: Travis, Circle, BrowserStack, SauceLabs).
  • chore:: Do not modify other parameterssrcortestFile.
  • revert:: commit Rollback.

Scope (scope)

You can add a scope enclosed in parentheses for the commit type to provide additional contextual information for it. For example feat(parser): adds ability to parse arrays.

BREAKING CHANGE

A commit with BREAKING CHANGE: at the beginning of an optional text or footnote indicates the introduction of a BREAKING API CHANGE (this corresponds to the MAJOR in the semantic version). Destructive changes can be part of any type of commit.

The sample

Contains descriptions and commit instructions for breaking changes in the body

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Copy the code

Includes optional!Character to alert attention to a destructive change

chore! : drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in AprilCopy the code

Submission notes that do not contain the body

docs: correct spelling of CHANGELOG
Copy the code

Contains a commit note for scope

feat(lang): add polish language
Copy the code

Submission notes for fix, including an (optional) issue number

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12
Copy the code

The contract form submits the specification

  1. Every submissionMust beUse the type field prefix, which consists of a noun, such asfeatorfix“Followed by oneoptionalScope field, and aThe necessaryColon and space.
  2. When a commit implements a new feature for an application or class library,Must beusefeatType.
  3. When a commit fixes a bug in an application,Must beusefixType.
  4. A scope field can follow a type field. There areMust beIs a noun that describes a section of code enclosed in parentheses, for example:fix(parser):
  5. Description fieldMust beImmediately after the space in the type/scope prefix. Description refers to a short summary of code changes, such as:fix:array parsing issue when multiplejspaces were contained in string.
  6. After a short description, you can write a longer commit body to provide additional contextual information for code changes. The body must start after a blank line that describes the end of the field.
  7. After a blank line at the end of the body, you can write one or more lines of footnotes. The footnote must contain meta information about the submission, such as: associated merge request, Reviewer, destructive change, one line per meta information.
  8. Destructive changeMust beIndicates at the beginning of a text area, or the beginning of a line in a footnote area. A disruptive changeMust beContains upper-case textBREAKING CHANGE, followed by a colon and space.
  9. inBREAKING CHANGE:afterMust beProvide a description to describe changes to the API. Such as:BREAKING CHANGE: enviroment variables now take precedence over cofig files.
  10. In the submission note,canusefeatandfixOther types.
  11. Implementation of the toolMust not beCase-sensitive parsing of the units of information that make up the contractual submission, onlyBREAKING CHANGE Must beIt’s uppercase.
  12. canAfter the type/scope prefix,:Before, attach!Character to further alert attention to destructive changes. When you have!The prefix must be included in the text or footnoteBREAKING CHANGE: description

Why do I use covenants

  • Automate production of CHANGELOG.
  • Semantic version changes are automatically determined based on the type of commit.
  • Communicate the nature of change to colleagues, the public, and other stakeholders.
  • Trigger the build and deploy process.
  • Let people explore a more structured submission history to make it easier to contribute to your project.

cz-customizable

A customizable Commitizen plug-in (or a standalone utility run) helps achieve consistent commit messages.

Install Commitizen, CZ-Customizable:

$ yarn add -D commitizen cz-customizable
Copy the code

Add a new script to package.json:

{
  "scripts": {..."commit": "git cz"
  }
  "config": {
    "commitizen": {
      "path": "cz-customizable"}}}Copy the code

Create.cz-config.js in the root directory and copy cz-config-example. js to the file.

Effect:

commitlint

Commitlint checks that your commit message conforms to the Conventional Commit format.

Install @commitlint/ CLI, husky:

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

Add git commit hooks to package.json:

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

Commitlint-config-cz (commitlint-config-cz)

Commitlint – config – cz merger of cz – customizable configuration {types, scopes, scopeOverrides} and commitlint configuration {type – enum, scope – enum}. This way, you can maintain both types and scopes in one place.

$ yarn add commitlint-config-cz -D
Copy the code

4, extend your commitlint configuration with cz in commitlint.config.js:

module.exports = {
  extends: ['cz'].rules: {
    // must add these rules
    'type-empty': [2.'never'].'subject-empty': [2.'never']}};Copy the code

vscode commitizen

Search for VS Code commitizen in VS Code and install VS Code Commitizen, then you can get away from the command line, and this plugin is compatible with all the previous configurations.

GitHub Actions

To create a new lot workflow. Making/workflows/commitlint yml, role pull_request the filing, check the information:

name: Lint Commit Messages
on: [pull_request]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v1
        with:
          node-version: '10.x'
      - run: npm install
      - name: Add dependencies for commitlint action
        # $GITHUB_WORKSPACE is the path to your repository
        run: echo "::set-env name=NODE_PATH::$GITHUB_WORKSPACE/node_modules"
      # Now the commitlint action will run considering its own dependencies and yours as well 🚀
      - uses: wagoid/commitlint-github-action@v2
Copy the code

standard-version

Standard-version is a version and Changelog automation tool that complies with the Semver and Commit Message standards. Normally, we will release the following version in the Master branch:

  1. git pull origin master
  2. According to thepackage.jsonIn theversionUpdate the version number and CHANGELOG
  3. git add .
  4. git commit
  5. git tagVersioning operation
  6. git push --tags: Push the version tag and master branch to the repository

2, 3, 4, and 5 are the ones that the standard-version tool automatically does, and with a local shell script, a series of releases can be automatically done.

Installation & Use

$ yarn add -D standard-version
Copy the code
// package.json
{
  "scripts": {
    "release": "standard-version"}}Copy the code
  • The First Release:yarn release --first-release
  • Cutting the Release:yarn release
  • Release as a pre-release:yarn release --prerelease or yarn release --prerelease alpha
  • Release as a Target Type Imperatively (npm version– like) :yarn release --release-as minor or Yarn release - release - as 1.1.0, can be merged--prereleaseThis facilitates the release of experimental features
  • Prevent the Git Hooks:yarn release --no-verify

This article was first published on the “official website of Luozhu”, as well as on the public account “Luozhu Morning Teahouse” and “Gold Column”.