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

;doc: contrib: commit conventions update

Browse Source
This commit is contained in:
Simon Michael 2021-07-04 11:47:25 -10:00
parent f260cf6b17
commit 6d0e133687
1 changed files with 56 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
CONTRIBUTING.md
View File

@ -509,58 +509,79 @@ Relevant tools include:
## Commit messages ## Commit messages
Starting with the 1.23 release cycle, Starting with the 1.23 release cycle, I'm proposing some new
I'm proposing some new [conventions](https://conventionalcommits.org) for commit messages. conventions for commit messages (WIP, will evolve as needed),
These are WIP and will evolve as we need. They are intended to: aiming to:
- reduce the cost of maintaining change docs (changelogs, release notes, announcements) - reduce the cost of maintaining change docs (changelogs, release notes, announcements)
- reduce the cost of releases - reduce the cost of releases
- encourage considered, focussed, well documented changes - encourage considered, focussed, well documented changes
- increase our throughput (the rate of shipping useful, reliable, documented, maintainable features) - increase our throughput (rate of shipping useful, reliable, documented, maintainable features)
1. Commit messages in hledger's main repo will follow this pattern: **hledger commit conventions:**
```
type: [optionaltopic:] summary
[Optional description, more details here when needed.] 1. Commit messages in hledger's main repo follow this pattern:
``` ```
type: [optionaltopic:] summary
2. The type prefix is one of the following: [Optional description, more details here when needed.]
```
- Changes visible to end users (including users of hledger-web's HTTP API) - 2. Every top-level commit must have a type prefix. This indicates the
these will be mentioned in release notes as well as changelogs. change's intended audience and the general type of change.
Here are the current types:
- `feat:` - a new feature - Changes visible to end users (including users of hledger-web's HTTP API).
- `imp:` - an improvement to existing features These will appear in release notes and changelogs:
- `fix:` - a bugfix
- Changes affecting packagers, builders (including users installing - `feat` - a new feature
from stackage or hackage), and library users (Haskell programmers - `imp` - an improvement to existing features
using our library APIs) - these will be mentioned in changelogs but - `fix` - a bugfix
usually not release notes.
- `cha:` - Changes affecting packagers, builders (including users installing
from stackage or hackage), and library users (Haskell programmers
using our library APIs). These will appear in changelogs, but not in release notes:
- Changes of interest only to developers/debuggers - - `cha` (or `pkg`, `lib` ?)
these will not be mentioned in changelogs or release notes.
- `;` - short spelling for convenience, think "commented out of changelogs". - Changes of interest only to hledger developers/documentors/debuggers;
these will be visible only in the commit history, not in changelogs or release notes:
3. A topic prefix, and maybe even a subtopic prefix, can be added if - `dev` (or `doc`, `ref`, `cln`, ... ?)
useful. These are standard prefixes similar to what I have been
using for some time (cf [labels](#labels),
[components](#components); I'll make an updated list in due
course). They help with readability in the commit history,
changelogs and release notes.
4. The summary, and description if any, communicate this change's 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 [components](#components).
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 target audience: end users, purpose as clearly as possible to its target audience: end users,
builders/packagers/library users, developers/debuggers. The text builders/packagers/library users, developers/debuggers. The text
should be ready for use in changelogs/release notes when applicable. should be ready for use in changelogs/release notes when applicable.
Crafting good commit messages (and thereby, good commits, and good Crafting good commit messages (and thereby, good commits, and good
change documentation) is an art and a habit; we'll try to check and change documentation) is an art and a habit; we'll check and satisfy
apply these conventions as part of CI and code review. these conventions as part of CI and code review.
Related:
- <https://conventionalcommits.org>
- <http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE> -> Commit messages
## Pull requests ## Pull requests