# 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`) ## Commits **When committing/reviewing:** Follow our [commit conventions](CONTRIBUTING.html#commit-messages): - 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. ## Changelogs Always maintain changelogs in main branch (not in release branches). **Frequently**, especially after merging changes, and before cherry picking into release branch: - dry run: `./Shake changelogs -n` - add new changes: `./Shake changelogs` - edit - drop things - move things - Add headings: Features, Improved, Fixes - rewrite things - format ([#ISSUE](https://github.com/simonmichael/hledger/issues/), AUTHOR) on its own line - commit: `./Shake changelogs -c` **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:** - do final update/edits; check organisation, wording, formatting, issue links - replace "unreleased" with the release date - copy the new sections from main changelogs to release branch changelogs ## Pre release 1. 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` 1. update changelogs in main 1. review changes so far, estimate which packages will be released 1. 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) ## Release - finalise [changelogs](#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 ## Post release - merge/check/update download page changes (docker, homebrew, nix, linux distros..) - support - handle issues - update procedures, tools, docs