Pitcher JavaScript Platform

# Conventional Commits

# Commit message convention

Commit messages have become a crucial part of the development process.

  • They allow you to trace back the point in time when you wrote that particular piece of code
  • They let other developers in your team track the flow of code
  • No one likes tracking code with messy commit messages
  • Since it is a summary of what changes you did, it is very important to write commit messages that are concise and consistent

There are many conventions around commit messages, that are widely followed in the developer community.

# What are Conventional Commits

The Conventional Commits (opens new window) specification is a lightweight convention on top of commit messages.
It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of.
This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

# Why Conventional Commits

  • Possibility to automatically generate CHANGELOGs
  • Possibility to automatically determine a semantic version bump (based on the types of commits landed)
  • Possibility to trigger build and publish processes
  • Communicating the nature of changes to teammates, the public, and other stakeholders
  • Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history

# Examples

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

feat: allow provided config object to extend other configs

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

# Commit message with ! to draw attention to breaking change

refactor!: drop support for Node 6

refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

# Commit message with no body

docs: correct spelling of CHANGELOG

# Commit message with scope

feat(lang): add polish language

# Commit message with multi-paragraph body and multiple footers

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

# Setup

Conventional commits is just a lightweight convention on top of commit messages.

You may

  • use some tools (e.g. create commit message helper)
  • lint your commit messages on git commit

You should

# Tools

In the Conventional Commits (opens new window) url you can find a plethora of tools.

e.g

# Lint commit messages on commit

# husky hook

Example using conventional-changelog/commitlint (opens new window)

Install commitlint cli and conventional config

npm install --save-dev @commitlint/{config-conventional,cli}

For Windows:

npm install --save-dev @commitlint/config-conventional @commitlint/cli

commitlint.config.js

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

package.json

  "husky": {
    "hooks": {
      "commit-msg": "npx --no-install commitlint --edit $1"
    }
  }

# GitHub Actions

# Lint messages during CI builds

Example using wagoid/commitlint-github-action (opens new window)

jobs:
  commit_lint:
    name: Commit Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v3

← Semantic Release →