@dfaas/commitlint-config NPM

DFAAS commitlint configuration

With this package a common, consistent commitlint configuration file, can be generated to ensure the same commit standards are used in across your projects. A abstraction of the commitlint configuration is made, so only the settings we want to be able to get changed across projects can be changed. Think about the issuesPrefixes allowed within the project, and the scopes allowed following the Conventional Commit standard.

Getting started

To get started with enforcing the Conventional Commit standard within your project, start with adding a commitlint.config.js file to the root of your repository with the contents below. Within this file the allowed issue prefixes and scopes can be configured specific for your project.

const { createCommitlintConfiguration } = require('@dfaas/commitlint-config');

module.exports = createCommitlintConfiguration({
  // List of allowed prefixes
  issuePrefixes: ['PROJ-'],
  // List of allowed scopes
  scopes: [],
});

Precommit can be used to enforce the commit messages by adding a .pre-commit-config.yaml file to the root of your project with the following content. In this way when commiting the commit message is directly validated.

repos:
  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
    rev: v9.11.0
    hooks:
      - id: commitlint
        stages: [commit-msg, manual]
        additional_dependencies: ['@dfaas/commitlint-config']

It is also possible to run commitlint manually against the last commit, for example as part of your CI process via pre-commit. The command below can be used for that.

touch .git/COMMIT_EDITMSG # Is not available at a fresh checkout and therefor crashes the pre-commit run below.
pre-commit run --hook-stage manual commitlint

Commit message guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. It also allows us to generate all kind of other files based on the commit messages.

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject. See the example below.

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

The header is mandatory and consists out of a type, a scope, and a subject of what happens when the commit is applied to the codebase. Imperative mood in present tense is used to write the subject, so change, not changed nor changes. To help to write a good subject the sentence If applied, my commit will <subject> can be used.

The header is not allowed to be longer than 100 characters. This allows the message to be easier to read on various git tools. It is written in all lower case and does not end with a dot (.).

Below the types can be found that are allowed to be used as part of the header.

Type	Description	SemVer
`build`	Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm, maven)
`chore`	Other changes that don't modify src or test files
`ci`	Changes to our CI configuration files and scripts (example scopes: Jenkins, Gitlab, Travis)
`docs`	Documentation only changes	PATCH
`feat`	A new feature	MINOR
`fix`	A bug fix	PATCH
`perf`	A code change that improves performance	PATCH
`refactor`	A code change that neither fixes a bug nor adds a feature
`revert`	Reverts a previous commit	PATCH
`style`	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
`tests`	Adding missing tests or correcting existing tests

Scopes that are allowed to be used are defined for each project separately. These are used to easily group related changes to a specific part of the project.

The body should include the motivation for the change and contrast this with previous behavior. Just as in the header use the imperative mood in present tense, so change, not changed nor changes.

The footer should contain a closing reference to an Jira issue. This can be done by using the following keywords, followed by the issue number.

Keywords	Single issue example	Multiple issues example
`close`, `closes`, `closed`	`Closes PROJ-61`	`Closes PROJ-61, closes PROJ-10`
`fix`, `fixes`, `fixed`	`Fixes PROJ-61`	`Fixes PROJ-61, fixes PROJ-10`
`resolve`, `resolves`, `resolved`	`Resolves PROJ-61`	`Resolves PROJ-61, resolves PROJ-10`

Breaking changes

Breaking changes should start with BREAKING CHANGE: followed by a space in the footer with a description of the change, justifications and notes on how to migrate. An example of the full commit structure is shown below.

feat: nam facilisis nisl at efficitur egestas

Body paragraph 1 - Donec congue massa, a pellentesque viverra vel. Quisque lacus,
faucibus porta quam quis, hendrerit ultrices purus. Vestibulum consequat ipsum nec ipsum
porttitor, id cursus mauris volutpat. Ut at augue malesuada lorem rutrum tristique.

Body paragraph 2 - Curabitur eu tellus augue. Nam facilisis nisl at efficitur egestas. Phasellus
id nibh consectetur, pulvinar mauris blandit, ornare magna.

BREAKING CHANGE: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ultricies purus nec
arcu eleifend elementum. Sed pretium, libero ac bibendum rhoncus, enim urna finibus lorem, ac
laoreet dolor nisi commodo nisl.

Donec consectetur, massa at suscipit sodales, ex mi varius nibh, id viverra mi risus id odio.
Praesent et elementum nisl. Phasellus lacinia justo lacinia tellus sollicitudin pharetra.

Fix PROJ-61, Closes PROJ-10, Resolve PROJ-16

Revert commit

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

dfaas commitlint precommit linting nfi

1 year ago

2 years ago

2 years ago

2 years ago