Releasing

Guidance for release managers and maintainers. Some of this might move elsewhere later.

Terminology

"main" / "main branch" = master branch in the main hledger repo (might get renamed in future)
"release" / "release branch" = a release branch in the main hledger repo (eg 1.22-branch)

When committing/reviewing:

Follow our commit conventions:

in the summary, use a feat:/imp:/fix: prefix (required for user-visible changes), and/or topic prefixes (bal:/areg:/test:/doc:/lib:/...)
add a leading ; to skip wasteful CI builds
add a ! to indicate breaking/incompatible changes
mention any relevant #issue numbers, usually parenthesised at the end
write the summary and at least the first part of the body, if any, as clear change documentation for the intended audience (users/installers/packagers/developers)

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.

Always maintain changelogs in main branch (not in release branches).

Frequently, especially after merging changes, and before cherry picking into release branch:

After cherry-picking changes to a release branch:

in the main branch changelogs, move the corresponding changelog items under a pending release heading, creating that when necessary:

# LATESTHASH

...CHANGES ONLY IN MASTER...

# NEXTVER unreleased

...CHANGES CHERRYPICKED INTO RELEASE BRANCH...

# LASTVER YYYY-MM-DD

At release:

create release branch when needed:
git branch MAJORVER-branch BRANCHPOINT
Sometimes, we make the major release tag (1.22) on master, and create a release branch (1.22-branch) when there's a followup minor release:
git branch 1.22-branch 1.22
update changelogs in main
review changes so far, estimate which packages will be released
cherry pick changes to release
- cherry pick 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 / other boring commits ("dev: doc: update changelogs")
- update changelogs in main (move corresponding change items under pending release heading)

finalise changelogs in main, copy to changelogs in release branch
./Shake.hs to update Shake and review release tasks
./Shake setversion VER [-c] (first without -c to review, then with -c to commit).
Also touch hledger/Hledger/Cli/Version.hs ?
./Shake cmdhelp [-c]
./Shake mandates
./Shake manuals [-c]
make tag
make hackageupload
push tags: magit P t
push to CI branches to test & generate binaries
- magit P -f e origin/ci-windows
- ... origin/ci-mac
- ... origin/ci-linux-static
- ... origin/ci-linux-static-arm32
in site: update download.md
in site: update relnotes.md
- copy template
- add new changelog sections, omitting hledger-lib
- add summary
- add contributors
update doc/ANNOUNCE
- summary/contributors from release notes
create github release
- tag VER, title VER, body similar to previous release
- at https://ci.hledger.org download each CI branch artifact when ready, to ~/Downloads/hledger-VER/
- drag artifacts into github draft release
- publish release
announce
- send ANNOUNCE to hledger@googlegroups.com, haskell-cafe@googlegroups.com
- link release notes/summary in #hledger:matrix.org, #hledger:libera.chat
- tweet at https://twitter.com/simonkwmichael
- toot at https://fosstodon.org/web/accounts/106304084994827771

merge/check/update download page changes (docker, homebrew, nix, linux distros..)
support
handle issues
update procedures, tools, docs