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]
- 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
fix:(feature, improvement, or bugfix). These will be used in release notes. If they are breaking/incompatible changes, use
- 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.
- 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.
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
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
commitlint also runs automatically on Github to check pull requests.