slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
91bfbbb437
hledger/COMMITS.md
Simon Michael 0fc4181456 ;doc: move more content out of CONTRIBUTING
2021-09-27 01:24:59 -10:00

4.9 KiB
Raw Blame History

COMMITS

When committing / reviewing commits

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. - 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.

When committing / pushing / merging:

  • run bin/commitlint 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

    • 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. 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: