doc: commits: update/rewrite

COMMITS.md

@@ -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).
+<!-- keep synced with tools/commitlint -->
-Here they are in brief:
+Here's the typical format:
--  Commit messages must begin with a prefix, one or more colon-terminated words
+
-   indicating the [topic](CONTRIBUTING.html#topics).
+    [feat|imp|fix[!]:] topic: Summary
--  Commits causing user-visible changes must additionally begin with `feat:`, `imp:` or `fix:` 
+
-   (feature, improvement, or bugfix). These will be mentioned in release notes.
+    [Longer description when useful]
--  Add a leading `;` to commits where a CI build is not needed, to reduce waste.
+
--  Add a `!` to highlight commits causing breaking/incompatible changes.
+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.
-
-## Commit conventions
-
-Since the 1.23 release cycle, we try to follow certain conventions for commit messages, to
-
-- 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)
-
-**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
- 
+- `dev` - a generic developer change
-   - **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...
+- Any of the standard [topics](ISSUES.html#topics) used in the issue tracker.
 
-    There's a bit of ambiguity/overlap between the cha/dev types and topics.
+## How to check commits
-    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
+Before committing, pushing, or merging, run `tools/commitlint` to check recent commit messages.
-   migration issue, the type is followed by `!`, and the issue
+(See the script for more ways to select commits.) You can configure your local working copy
-   and advice to users are included in the description.
+to do this automatically, by running `make installcommithook`.
-   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
+commitlint also runs automatically on Github to check pull requests.
-   (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
+## See also
-   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:
 
 - <https://groups.google.com/g/hledger/c/t14xwHQMJqU/m/9frARXIdAAAJ>
 - <https://conventionalcommits.org>