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

83
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
- `imp` - an improvement to existing features
- `fix` - a bugfix
- Changes affecting packagers, builders (including users installing
from stackage or hackage), and library users (Haskell programmers from stackage or hackage), and library users (Haskell programmers
using our library APIs) - these will be mentioned in changelogs but using our library APIs). These will appear in changelogs, but not in release notes:
usually not release notes.
- `cha:` - `cha` (or `pkg`, `lib` ?)
- Changes of interest only to developers/debuggers - - Changes of interest only to hledger developers/documentors/debuggers;
these will not be mentioned in changelogs or release notes. these will be visible only in the commit history, not in changelogs or release notes:
- `;` - short spelling for convenience, think "commented out of changelogs". - `dev` (or `doc`, `ref`, `cln`, ... ?)
3. A topic prefix, and maybe even a subtopic prefix, can be added if 3. If this is a "breaking change", introducing a compatibility or
useful. These are standard prefixes similar to what I have been migration issue, the type is followed by `!`, and the issue
using for some time (cf [labels](#labels), and advice to users are included in the description.
[components](#components); I'll make an updated list in due This will most often be seen with the end-user types, eg:
course). They help with readability in the commit history, `feat!:`, `imp!:`, `fix!:`.
changelogs and release notes.
4. The summary, and description if any, communicate this change's 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