COMMITS

In the hledger project we try to follow certain conventions for commit messages, because good messages lead to good commits => good change docs => easier code review => quicker merging => faster delivery of quality software. We'll check and help you polish messages as part of CI and code review. (You can also set up a local commit hook, described below.)

Here's the typical format: 

[feat|imp|fix[!]:] topic: Summary

[Longer description when useful]

More precisely:

  • Commit messages must begin with one or more prefixes (colon-terminated words), indicating the type and/or topic.
  • Commits causing user-visible changes must begin with feat:, imp: or fix: (feature, improvement, or bugfix). These will be used in release notes. If they are breaking/incompatible changes, use feat!:, imp!: or fix!:.
  • To skip CI builds on commits which would normally trigger one, add a ; at the beginning. (Our CI does a lot of work, so you can use this to reduce energy waste and carbon emissions from minor changes. Non-code commits do this automatically.)
  • Mention any relevant issue numbers, usually parenthesised at the end. (#NNNN)
  • Try to write commit messages as changelog/release-note-ready documentation that will tell their intended audience (which might be users, installers, packagers, and/or developers) what they need to know.

Some examples:

  • feat: accounts: --types shows account types (#1820)
  • imp!: journal: Remove deprecated account type code syntax from account directives.
  • fix: types: Ensure auto postings can match against and be matched by type: queries.
  • tools: commitlint: allow a git "fixup! " prefix
  • doc: releasing: tweaks

Some possible prefixes:

  • feat - a new feature
  • imp - an improvement to existing features
  • fix - a bugfix
  • dev - a generic developer change
  • ref - refactoring
  • cln - cleanup
  • doc - documentation-related
  • test - tests-related
  • ci - continuous integration-related
  • Any of the standard labels used in the issue tracker.

How to check commits

Before committing, pushing, or merging, run tools/commitlint to check recent commit messages. (See the script for more ways to select commits.) You can configure your local working copy to do this automatically, by running just installcommithook.

commitlint also runs automatically on Github to check pull requests.

See also