diff --git a/COMMITS.md b/COMMITS.md index cdb4986e8..31773be58 100644 --- a/COMMITS.md +++ b/COMMITS.md @@ -4,110 +4,64 @@ -## When committing / reviewing 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.) -Follow/encourage the commit conventions (see below). -Here they are in brief: -- Commit messages must begin with a prefix, one or more colon-terminated words - indicating the [topic](CONTRIBUTING.html#topics). -- Commits causing user-visible changes must additionally begin with `feat:`, `imp:` or `fix:` - (feature, improvement, or bugfix). These will be mentioned in release notes. -- Add a leading `;` to commits where a CI build is not needed, to reduce waste. -- Add a `!` to highlight commits causing breaking/incompatible changes. -- Mention any relevant issue numbers, usually parenthesised at the end. `(#NNNN)` -- Try to write commit messages as changelog-ready documentation that will tell their - intended audience (which might be users, installers, packagers, and/or developers) - what they need to know. + +Here's the typical format: -## When committing / pushing / merging: + [feat|imp|fix[!]:] topic: Summary -- run `tools/commitlintnt` before push, to check recent commits -- or, run it automatically before each commit (`make installcommithook` to configure your local repo) -- it also runs in CI on github for pull requests, etc. + [Longer description when useful] -## Commit conventions +Some examples: -Since the 1.23 release cycle, we try to follow certain conventions for commit messages, to +- *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* -- encourage considered, focussed, well documented changes -- reduce the cost of code review, maintaining changelogs and release notes, and releasing -- increase our throughput (rate of shipping useful, reliable, documented, maintainable features) +More precisely: -**hledger commit conventions:** +- 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. -1. Commit messages in hledger's main repo follow this pattern: - ``` - type: [optionaltopic:] summary - - [Optional description, more details here when needed.] - ``` +Some possible prefixes: -2. Every top-level commit must have a type prefix, ending with a colon and optional space. - This indicates the change's intended audience and the general type of change. - Here are the current types: +- `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. - - **Changes visible to end users** (including users of hledger-web's HTTP API). - These will appear in release notes and changelogs: - - - `feat` - a new feature - - `imp` - an improvement to existing features - - `fix` - a bugfix - - - **Changes affecting packagers, builders, and library users**. - These will appear in changelogs: - - - `cha` - a generic package/lib change. Or, one of these specific types: - - `pkg` - something to do with the haskell packages, dependencies etc. - - `lib` - a change in the package's library API - - ...some other type that seems useful... +## How to check commits - - **Changes interesting only to hledger developers/documentors/debuggers**. - These will usually appear only in the commit history, not in changelogs or release notes: - - - `dev` - a generic developer change. Or, one of these specific types: - - `ref` - refactoring - - `cln` - cleanup - - `doc` - documentation-related - - `test` - tests-related - - `ci` - continuous integration-related - - ...some other type that seems useful... - - There's a bit of ambiguity/overlap between the cha/dev types and topics. - Eg the `doc` type indicates a boring doc change, but there's also a `doc` topic - which might be used for interesting doc changes, as in `feat:doc:...`. TBD. +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`. -3. If this is a "breaking change", introducing a compatibility or - migration issue, the type is followed by `!`, and the issue - and advice to users are included in the description. - This will most often be seen with the end-user types, eg: - `feat!:`, `imp!:`, `fix!:`. +commitlint also runs automatically on Github to check pull requests. -4. If the first character of the commit message is `;`, this commit - (more precisely, the push ending with this commit) will be excluded - from the usual CI checks. Our CI tends to do a lot of building, so - you can use this to save energy and carbon emissions when pushing - harmless changes. - -5. A topic prefix, and maybe even a subtopic prefix, can be added - before the summary if useful. These are standard prefixes similar - to what I have been using for some time, see [topics](#topics). - They help with readability in the commit history, changelogs and release notes. - -6. Any relevant issues should be mentioned, often parenthesised at - the end of the summary: `(#NNNN)`. - -7. The summary, and description if any, communicate this change's - purpose as clearly as possible to its intended audience: - end users, builders/packagers/library users, or developers/debuggers. - The text (or its first sentence/first paragraphs) should be ready - for use in changelogs/release notes when applicable. - -Crafting good commit messages (and thereby good commits, good change -documentation, easier code review, faster merging) is an art and a -habit. Just use your best judgement and we'll check and polish -as part of CI and code review. Examples will be added here in due course. - -Related: +## See also - -