diff --git a/RELEASING.md b/RELEASING.md index fa51938ea..474da2b3c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,58 +1,150 @@ # Releasing Guidance for release managers and maintainers. +Some of this might move elsewhere later. -Terminology: +## 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`. +- "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 `tools/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. +Always maintain changelogs in main branch (not in release branches). -Apply [CONTRIBUTING.md#commit-messages](CONTRIBUTING.html#commit-messages) rules -when commiting, pushing, or reviewing/merging pull requests. -`tools/commitlint` helps with this, run locally and in CI. +**At start of release cycle:** +- add the next release heading, with date "unreleased", above last release heading: -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` - -1. update main changelogs - - `./Shake changelogs` - - do at least basic editing - drop things, move things - - `./Shake changelogs -c` - -1. review changes so far, estimate which packages will be released - -1. add "unreleased" minor release heading in main changelogs, immediately above previous release heading ``` # LATESTHASH - ... - - # X.Y.1 unreleased <- new heading + ...CHANGES... - # X.Y YYYY-MM-DD + # NEXTVER unreleased <- ADD + + # LASTVER YYYY-MM-DD ``` +**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: +- move the corresponding changelog items under the pending release heading. + +**At release:** + +- do final update/edits; check organisation, wording, formatting, issue links +- replace "unreleased" with the date in the pending release heading +- copy the new release sections from main changelogs to release branch changelogs + +## Pre release + +1. create release branch when needed:\ + `git branch MAJORVER-branch BRANCHPOINT`\ + When convenient, the first major release can be tagged on master (`1.22`), + and the release branch (`1.22-branch`) gets created 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 - 1. always update main changelogs first - 2. cherry pick minor-release-worthy commits + - 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`) + (`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 + - ignore changelog commits / other boring commits + ("dev: doc: update changelogs") -1. finalise release - - add date to minor release heading in main changelogs - - copy the minor release section from main changelogs to release changelogs +1. in 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