;doc: RELEASING: updates

RELEASING.md

@@ -9,8 +9,12 @@ Some of this might move elsewhere later.
 
 ## Terminology
 
-- "main" / "main branch" = `master` branch in the main hledger repo (might get renamed in future)
+- **OLD** - previous release version, eg `1.22` or `1.22.1`
-- "release" / "release branch" = a release branch in the main hledger repo (eg `1.22-branch`)
+- **NEW** - new release version, eg `1.22.2` or `1.23`
+- **MAJORVER** - just the major version part, eg `1.22` or `1.23`
+- **master** / **master branch** - `master` branch in the main hledger repo
+- **release** / **release branch** - a release branch in the main hledger repo, named MAJORVER-branch, eg `1.22-branch`
+- **site** / **site repo** - master branch in the hledger_website repo, usually cloned under the main repo as `site`
 
 ## Commits
 
@@ -33,7 +37,7 @@ Follow our [commit conventions](CONTRIBUTING.html#commit-messages):
 
 ## Changelogs
 
-Always maintain changelogs in main branch (not in release branches).
+Always maintain changelogs in master branch (not in release branches).
 
 **Frequently**, especially after merging changes, and before cherry picking into release branch:
 
@@ -48,7 +52,7 @@ Always maintain changelogs in main branch (not in release branches).
 - 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,
+- in the master branch changelogs, move the corresponding changelog items under a pending release heading,
   creating that when necessary:
     ```
     # LATESTHASH
@@ -66,17 +70,17 @@ Always maintain changelogs in main branch (not in release branches).
 
 - 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
+- copy the new sections from master changelogs to release branch changelogs
 
-## Pre release
+## Release prep
 
 1. create release branch when needed:\
   `git branch MAJORVER-branch BRANCHPOINT`\
-   Sometimes, we make the major release tag (`1.22`) on master,
+   Sometimes when convenient we make major releases on master (adapt the steps below as needed).
-   and create a release branch (`1.22-branch`) when there's a followup minor release:\
+   And make the release branch later, when a minor release becomes necessary, eg:\
   `git branch 1.22-branch 1.22`
 
-1. update changelogs in main
+1. update changelogs in master
 
 1. review changes so far, estimate which packages will be released
 
@@ -88,62 +92,118 @@ Always maintain changelogs in main branch (not in release branches).
         - ignore changelog commits / other boring commits 
           ("dev: doc: update changelogs")
 
-    - update changelogs in main (move corresponding change items under pending release heading)
+    - update changelogs in master (move corresponding change items under pending release heading)
 
-## Release
+## Release day
 
-- finalise [changelogs](#changelogs) in main,
+In master:
-  copy to changelogs in release branch
 
-- `./Shake.hs` to update `Shake` and review release tasks
+- `./Shake.hs` to ensure `Shake` is current, review commands
 
-- `./Shake setversion VER [-c]` (first without `-c` to review, then with `-c` to commit).\
+- finalise [changelogs](#changelogs), copy each new section (emacs `C-x r s a` ... `b` ... `c` ... `d`)
-  Also `touch hledger/Hledger/Cli/Version.hs` ?
+
+In release branch:
+
+- paste new sections into changelogs
+
+- `./Shake setversion NEWVER [-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]`
+- `./Shake manuals -B [-c]`  (using up to date doctool versions)
 
-- `make tag`
+- `make tag`  (signed annotated tags for each package and the overall release)
 
-- `make hackageupload`
+- `stack clean && stack install && hledger --version && hledger-ui --version && hledger-web --version`
-
+  to build locally and check version strings
-- push tags: magit `P t`
 
 - push to CI branches to test & generate binaries
   - magit `P -f e origin/ci-windows`
-  - ... `origin/ci-mac`
+  - magit `P -f e origin/ci-mac`
-  - ... `origin/ci-linux-static`
+  - magit `P -f e origin/ci-linux-static`
-  - ... `origin/ci-linux-static-arm32`
+  - magit `P -f e origin/ci-linux-static-arm32` if needed
 
-- in site: update `download.md`
+In site repo:
 
-- in site: update `relnotes.md`
+- update `download.md`
-  - copy template
+  - outputs in --version examples (search: hledger --version)
-  - add new changelog sections, omitting hledger-lib
+  - final output line from `hledger test` (run in terminal for normal speed)
-  - add summary
+  - query-replace OLD -> NEW in 
-  - add contributors
+    - "current hledger release"
+    - CI binaries badges/links, including linux-static-arm32v7 if built
+    - "building from source"
+    - stack install command
+    - cabal install command
+  - query-replace OLD-brightgreen -> OLD-red
+  - commit: `download: NEW`
 
-- update `doc/ANNOUNCE`
+- update `relnotes.md`
-  - summary/contributors from release notes
+  - copy template, uncomment
+  - replace date
+  - replace XX with NEW
+  - add new changelog sections, excluding hledger-lib
+  - remove any empty sections
+  - add contributors, `git shortlog -sn OLD..NEW`
+  - add summary (major release) or remove it (minor release)
+  - check preview in vs code
+  - commit: `relnotes: NEW`
+
+In release branch:
+
+- update `doc/ANNOUNCE` (major release)
+  - summary, contributors from release notes
+  - any other edits
+  - commit: `;doc: ANNOUNCE`
+
+In master:
+
+- cherry pick useful release branch changes
+  - `;doc: ANNOUNCE`
+
+- wait for CI binaries, https://ci.hledger.org
+
+- pre-release pause: take a break away from keyboard
+
+## Release
+
+In release branch:
+
+- review status, reflect
+
+- `make hackageupload`
+
+- push tags: magit `P t origin`
 
 - create github release
-  - tag VER, title VER, body similar to previous release
+  - https://github.com/simonmichael/hledger/releases, copy last release's body
-  - at https://ci.hledger.org download each CI branch artifact when ready, to ~/Downloads/hledger-VER/
+  - create new release from NEW tag if CI workflow has failed
-  - drag artifacts into github draft release
+  - tag NEW, title NEW, body similar to previous release
+  - at https://ci.hledger.org download CI binary artifacts, check sizes look similar to previous
+  - select downloaded artifacts in Finder, drag into github release
   - publish release
 
 - announce
-  - send ANNOUNCE to hledger@googlegroups.com, haskell-cafe@googlegroups.com
+  - push website download/relnotes updates
-  - link release notes/summary in #hledger:matrix.org, #hledger:libera.chat
+  - share release notes link, summary in #hledger:libera.chat
-  - tweet at https://twitter.com/simonkwmichael
+  - share release notes link, summary, release notes markdown in #hledger:matrix.org
-  - toot at https://fosstodon.org/web/accounts/106304084994827771
+  - send ANNOUNCE to hledger@googlegroups.com, haskell-cafe@googlegroups.com (major release)
+    or brief announcement to hledger@googlegroups.com (minor release)
+    - ANN: hledger NEW
+    - release notes link, summary
+    - release notes html (copied from browser)
+  - 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..)
+- merge/check/update download page changes
+  - docker - expect/merge PR
+  - homebrew - expect badge to update soon
+  - nix - expect `make nix-hledger-version` to update after a few days, find and update to that commit hash
+  - linux distros - once in a while, follow the links & search for newer versions, update
 
 - support