slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: commits: update/rewrite

Browse Source
This commit is contained in:
Simon Michael 2022-02-07 11:28:41 -10:00
parent cddc719bd1
commit 223c60222e
1 changed files with 45 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
COMMITS.md
View File

@ -4,110 +4,64 @@
<!-- toc -->
</div>
## 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.
<!-- keep synced with tools/commitlint -->
Here's the typical format:
[feat|imp|fix[!]:] topic: Summary
[Longer description when useful]
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*
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-ready documentation that will tell their
- 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.
## When committing / pushing / merging:
Some possible prefixes:
- 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.
- `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.
## Commit conventions
## How to check commits
Since the 1.23 release cycle, we try to follow certain conventions for commit messages, to
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`.
- 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)
commitlint also runs automatically on Github to check pull requests.
**hledger commit conventions:**
1. Commit messages in hledger's main repo follow this pattern:
```
type: [optionaltopic:] summary
[Optional description, more details here when needed.]
```
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:
- **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...
- **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.
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!:`.
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
- <https://groups.google.com/g/hledger/c/t14xwHQMJqU/m/9frARXIdAAAJ>
- <https://conventionalcommits.org>