hledger/RELEASING.md

Releasing

Guidance for release managers and maintainers.

Terminology:

• “main” = the master branch in the main hledger repo (might be renamed to main in future).
• “release” = a release branch in the main hledger repo, such as 1.22.

Changelogs

Always maintain changelogs in main.

Apply CONTRIBUTING.md#commit-messages rules when commiting, pushing, or reviewing/merging pull requests. tools/commitlint helps with this, run locally and in CI.

Use ./Shake changelogs to update them from recent commit messages.

Minor release

Checklist:

1. create release branch if none
   git branch RELEASEBRANCH RELEASETAG
git branch 1.22-branch 1.22

2. update main changelogs

   • ./Shake changelogs
   • do at least basic editing - drop things, move things
   • ./Shake changelogs -c

3. review changes so far, estimate which packages will be released

4. add “unreleased” minor release heading in main changelogs, immediately above previous release heading ``` # LATESTHASH

   …

   # X.Y.1 unreleased <- new heading

   # X.Y YYYY-MM-DD ```

5. cherry pick changes to release

   1. always update main changelogs first
   2. cherry pick minor-release-worthy commits
      • from: magit, l o X.Y..master, M-x magit-toggle-buffer-lock, C-x D (M-x toggle-window-dedicated)
      • to: magit, l o master..X.Y, M-x magit-toggle-buffer-lock, C-x D
      • ignore commits already seen in previous cherry picking sessions
      • ignore changelog commits (“dev: doc: update …”)
   3. in main changelogs, move corresponding change items under minor release heading

6. finalise release

   • add date to minor release heading in main changelogs
   • copy the minor release section from main changelogs to release changelogs