hledger/COMMITS.md

70 lines
2.7 KiB
Markdown

# COMMITS
<div class=pagetoc>
<!-- toc -->
</div>
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: <!-- keep synced with tools/commitlint -->
[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](ISSUES.html#topics).
- 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 [topics](ISSUES.html#topics) 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 `make installcommithook`.
commitlint also runs automatically on Github to check pull requests.
## See also
- <https://groups.google.com/g/hledger/c/t14xwHQMJqU/m/9frARXIdAAAJ>
- <https://conventionalcommits.org>
- <https://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE> -> Commit messages