diff --git a/doc/RELEASING.canvas b/doc/RELEASING.canvas index eb38f4dc8..95ca43734 100644 --- a/doc/RELEASING.canvas +++ b/doc/RELEASING.canvas @@ -1,7 +1,5 @@ { "nodes":[ - {"type":"text","text":"Release binaries\n","id":"07112d859abf3940","x":-159,"y":370,"width":191,"height":50,"color":"#f58f00"}, - {"type":"text","text":"Passing platform CIs","id":"4af91a6bc27a1008","x":-187,"y":450,"width":250,"height":60,"color":"#f58f00"}, {"type":"text","text":"Up-to-date help","id":"92dda98079ab4d1e","x":80,"y":1080,"width":191,"height":55,"color":"5"}, {"type":"text","text":"Up-to-date changelogs","id":"e8e90d5c5cc42241","x":-404,"y":1127,"width":224,"height":60,"color":"5"}, {"type":"text","text":"Features, improvements, fixes","id":"1b38487f9fac1e2c","x":-206,"y":1270,"width":309,"height":60,"color":"6"}, @@ -14,7 +12,6 @@ {"type":"text","text":"LEVEL 1 - DEV","id":"1e09c093e184f1ff","x":-940,"y":1270,"width":280,"height":60,"color":"6"}, {"type":"text","text":"LEVEL 2 - TEST","id":"80cb496c45b89756","x":-940,"y":940,"width":280,"height":60,"color":"5"}, {"type":"text","text":"LEVEL 3 - RELEASE DOCS","id":"0a51f5cec92dcd0a","x":-940,"y":540,"width":280,"height":60,"color":"#ffdd00"}, - {"type":"text","text":"LEVEL 4 - RELEASE READY","id":"62ae958cd2ff139c","x":-940,"y":280,"width":280,"height":60,"color":"#f58f00"}, {"type":"text","text":"LEVEL 6 - PUBLISHED","id":"6b0c017479931f0a","x":-940,"y":-390,"width":280,"height":60,"color":"4"}, {"type":"text","text":"LEVEL 7 - ANNOUNCED","id":"0813225d75c39151","x":-940,"y":-550,"width":280,"height":60,"color":"#007508"}, {"type":"text","text":"Website","id":"187d7edfa7e9f024","x":0,"y":-390,"width":155,"height":60,"color":"4"}, @@ -27,16 +24,20 @@ {"type":"text","text":"Hackage packages\n(Major, bugfix, fixup)","id":"52c90a00d0b573af","x":-512,"y":120,"width":248,"height":80,"color":"1"}, {"type":"text","text":"Good urls, redirects, structure","id":"b4b160df1e279f6d","x":165,"y":-280,"width":315,"height":32,"color":"4"}, {"type":"text","text":"Install page\n(Major, bugfix, fixup)","id":"42f027c1822c2021","x":-206,"y":-280,"width":233,"height":70,"color":"4"}, - {"type":"text","text":"hledger-install.sh\n(Major, bugfix, fixup)","id":"05062529ce2b5d9a","x":-747,"y":-280,"width":268,"height":70,"color":"4"}, + {"type":"text","text":"Continually updated\nhledger-install.sh in master\n","id":"05062529ce2b5d9a","x":-747,"y":-280,"width":268,"height":70,"color":"4"}, {"type":"text","text":"Release changelogs","id":"82f800fbaf1fff31","x":-190,"y":641,"width":250,"height":60,"color":"#ffdd00"}, {"type":"text","text":"Release version number","id":"3dede0e33cab04ab","x":-193,"y":741,"width":258,"height":60,"color":"#ffdd00"}, {"type":"text","text":"Release branch","id":"2f72dd0306686404","x":-166,"y":841,"width":205,"height":60,"color":"#ffdd00"}, {"type":"text","text":"Release notes\n(Major, bugfix)","id":"4626d11550a5dd82","x":-200,"y":541,"width":270,"height":60,"color":"#ffdd00"}, - {"type":"text","text":"Release tag","id":"ee51d1acdb16f4ed","x":-151,"y":280,"width":172,"height":60,"color":"#f58f00"}, - {"type":"text","text":"Github release","id":"48113316f596b226","x":-190,"y":140,"width":250,"height":60,"color":"1"}, {"type":"text","text":"Passing tests and CI","id":"cd072c3e5f37fc77","x":-204,"y":940,"width":284,"height":60,"color":"5"}, {"type":"text","text":"Up-to-date manuals","id":"c11b65fbcab6d67a","x":-172,"y":1108,"width":220,"height":50,"color":"5"}, - {"type":"text","text":"LEVEL 5 - RELEASED","id":"4c7d316dc60a406d","x":-940,"y":100,"width":280,"height":60,"color":"1"} + {"type":"text","text":"LEVEL 5 - RELEASED","id":"4c7d316dc60a406d","x":-940,"y":100,"width":280,"height":60,"color":"1"}, + {"type":"text","text":"LEVEL 4 - RELEASE BINARIES","id":"62ae958cd2ff139c","x":-940,"y":370,"width":280,"height":60,"color":"#f58f00"}, + {"type":"text","text":"Passing platform CI tests","id":"4af91a6bc27a1008","x":-190,"y":450,"width":250,"height":60,"color":"#f58f00"}, + {"type":"text","text":"Release binaries\n","id":"07112d859abf3940","x":-160,"y":370,"width":191,"height":50,"color":"#f58f00"}, + {"type":"text","text":"Release tag","id":"ee51d1acdb16f4ed","x":-151,"y":260,"width":172,"height":60,"color":"1"}, + {"type":"text","text":"Github release","id":"48113316f596b226","x":-190,"y":140,"width":250,"height":60,"color":"1"}, + {"type":"text","text":"hledger-install.sh","id":"5d888a29bcefdde3","x":-603,"y":370,"width":250,"height":60,"color":"#f58f00"} ], "edges":[ {"id":"1cbe2796fa62185f","fromNode":"52d90724c458c2d2","fromSide":"bottom","toNode":"2d971da3a664c356","toSide":"top"}, @@ -80,6 +81,7 @@ {"id":"c15e04d54adbe3b7","fromNode":"cd072c3e5f37fc77","fromSide":"bottom","toNode":"887e2b1b907d0ac9","toSide":"top"}, {"id":"70b80ea2ea092fd0","fromNode":"5fa590b519f60b9b","fromSide":"bottom","toNode":"187d7edfa7e9f024","toSide":"top"}, {"id":"83ace9eece04a0c9","fromNode":"42f027c1822c2021","fromSide":"bottom","toNode":"05062529ce2b5d9a","toSide":"top"}, - {"id":"c32288130f1142dc","fromNode":"42f027c1822c2021","fromSide":"bottom","toNode":"07112d859abf3940","toSide":"right"} + {"id":"c32288130f1142dc","fromNode":"42f027c1822c2021","fromSide":"bottom","toNode":"07112d859abf3940","toSide":"right"}, + {"id":"08d117f41a7cd9db","fromNode":"05062529ce2b5d9a","fromSide":"left","toNode":"5d888a29bcefdde3","toSide":"top"} ] } \ No newline at end of file diff --git a/doc/RELEASING.md b/doc/RELEASING.md index 92023fb8a..8319817ea 100644 --- a/doc/RELEASING.md +++ b/doc/RELEASING.md @@ -107,16 +107,17 @@ To do a release, start at the bottom of the diagram and work up ### General tips -- Update changelogs early and often, eg during/after a PR, to spread the work. - See also [CHANGELOGS](CHANGELOGS.html). -- Release (or practice releasing) often. -- Use and continually update the process notes in RELEASING.md. -- Copy it to RELEASING2.md when starting and update the copy until done, to reduce git hassle. +- Release (or practice releasing) often to improve the process. +- Use and continually update RELEASING.md and RELEASING.canvas. +- At the start of any release work, copy these (eg Obsidian > CMD-p > Make a copy of this file). Edit in the copies until done, to avoid blocking git branch switching. (Likewise if editing other docs, like CHANGELOGS.md.) - Don't document procedures in too much detail / prematurely. - Make things a little better each time through: simpler, more reliable, better documented, more automated, easier, faster, cheaper, higher quality. -- Make releases from a release branch, not from master. -- Use the tools/release script. -- Binaries' --version shows their git hash and build date; these should match the release tag and release date. +- `make`, `./Shake` and `./bake`. +- Update changelogs early and often, eg during/after a PR, to spread the work. + See also [CHANGELOGS](CHANGELOGS.html). +- Do releases from a release branch, not from master. +- All platform binaries should be built from the same commit, the one with the release tags. +- Binaries' --version shows their git hash and build date; these should match the release tag and release date. ### LEVEL 1 - DEV @@ -129,6 +130,14 @@ To do a release, start at the bottom of the diagram and work up ### LEVEL 2 - TEST +Give it a few shakes. + +#### Up-to-date tools +- ./Shake is up to date + - Shake.hs uses same resolver, extra deps etc. as stack.yaml + - Shake binary is up to date (`./Shake.hs`) + - commit any changes (message: "tools: shake") + #### Up-to-date cabal files - `./Shake cabalfiles` - if there are changes, `./Shake cabalfiles -c` @@ -143,43 +152,34 @@ To do a release, start at the bottom of the diagram and work up - if there are changes, `./Shake manuals -c` #### Up-to-date changelogs -in main repo, master branch: +In main repo, master branch: - `./Shake changelogs` - clean up the five `CHANGES.md`s - `./Shake changelogs -c` -See also [CHANGELOGS](CHANGELOGS.md). +See [CHANGELOGS](CHANGELOGS.md). #### Passing tests and CI -- `make functest` -- `make test` -- `make bench` ? -- `make haddocktest` ? -- CI tests in github main repo +- local tests, mimicking CI + - `make test` + - `make doctest` + - `make haddocktest` +- single-platform CI tests in github main repo master + (if needed; not easy for a release branch, multi-platform CI tests will come later) - push to a PR, wait for green - or push to `simon` branch, wait for green at http://ci.hledger.org - or `tools/push` (pushes to `simon`, then to `master`) -#### Check documented -- master's changelogs are up to date (see [CHANGELOGS](CHANGELOGS.html)) -- master or release branch is ready for release - - clean and synced working copy - - no pending release-blocking issues/prs - - tests pass -- Shake is up to date - - uses same resolver as stack.yaml - - uses any required workarounds in stack.yaml - - binary is up to date (`./Shake.hs`) - - commit any changes (msg: `tools: shake`) - ### LEVEL 3 - RELEASE DOCS -#### Copy RELEASING.md -- copy of RELEASING.md to RELEASING_.md; make updates in the copy +Bake it ? Try `bash -x ./bake prep VERSION` next time. Warning, avoid possible bug with being in master instead. Does a bunch of stuff including partly finalising changelogs. + +#### Release branch + +Bugfix/fixup release: +- switch to release branch, cherry pick changes from master -#### Prepare release branch Preview/major release: - -- `PAUSE=1 ECHO=1 tools/release prep MA.JOR[.99.PREVIEWNUM]` (eg 1.24.99.1 for 1.25 preview 1) +- `PAUSE=1 ECHO=1 ./bake prep MA.JOR[.99.PREVIEWNUM]` (eg 1.24.99.1 for 1.25 preview 1) (XXX seems to go wrong without PAUSE`) - clean up changelogs, amend changelogs commit (see also [CHANGELOGS](CHANGELOGS.html)) - cherry pick changes from master (if needed) @@ -194,76 +194,100 @@ Preview/major release: - `stack build --test` - `make functest` -Bugfix/fixup release: -- cherry pick changes from master - #### Release version number -- choose new version (NEW): MA.JOR, MA.JOR.MINOR, or MA.JOR.MINOR.FIXUP -- on release branch do `./Shake setversion -c NEW` +- Choose new version (NEW): MA.JOR, MA.JOR.MINOR, or MA.JOR.MINOR.FIXUP +- In release branch do `./Shake setversion -c NEW` #### Release changelogs +- add release version/date headings manually (or fix `bake prep`, then clean up manually) #### Release notes -In site repo: +In site repo, update `src/release-notes.md`: +- copy template, uncomment +- replace date +- replace XX with NEW +- add new content from changelogs, excluding hledger-lib +- remove any empty sections +- add contributors, `git shortlog -sn OLD..NEW` +- add summary (major release) or remove it (bugfix release) +- site repo commit: `relnotes: NEW` -- update `src/release-notes.md` - - copy template, uncomment - - replace date - - replace XX with NEW - - add new content from changelogs, excluding hledger-lib - - remove any empty sections - - add contributors, `git shortlog -sn OLD..NEW` - - add summary (major release) or remove it (bugfix release) - - check preview in vs code - - site repo commit: `relnotes: NEW` +### LEVEL 4 - RELEASE BINARIES -### LEVEL 4 - RELEASE READY - -#### Release binaries -- do a preliminary push to `origin/binaries` -- resolve failures -- wait for any pending successful builds to complete and update cache -- `tools/release bin` -- get all platforms built on the same commit -- delete any local downloaded binaries from last release -- download binary artifact zip files (on each successful run: right click, download linked file) - -#### Release build testing +#### Release build tests - touch/change Version.hs to encourage recompilation - `stack build` - `stack exec -- hledger --version`, check version, hash, release date, no '+' - `stack exec -- hledger help | tail`, check version, month matches release -#### Release tag -- ensure new version has been set with Shake setversion ! -- `make tag` +#### Platform CI tests +Multi-platform CI tests: +- push to `github/binaries` (or `./bake bin`) +- resolve failures +- wait for green on all platforms -#### Pre-release tests -- appropriate dates in: changelogs, release notes, --version output, man pages, hledger-install script +#### Release binaries +Once all platform CI tests are green: +- in local downloads dir, delete any zip files from last release +- in each successful platform job: right click, Download linked file +- unpack the zip file for local platform +- on that same commit, build native local binaries: + - `make install-as-VERSION` -#### Check release ready / pre-release pause +#### hledger-install script +(major/bugfix/fixup release) +- update `hledger-install/hledger-install.sh` + - HLEDGER_INSTALL_VERSION (release date) + - hledger official packages (NEW) + - hledger third-party packages (latest versions on hackage/pypi) + - RESOLVER and EXTRA_DEPS (same as stack.yaml, or one of them) +- test ? (won't work until new hledger packages are on hackage) + `cd; bash ~/src/hledger/hledger-install/hledger-install.sh` +- commit: `install: NEW` + +### LEVEL 5 - RELEASED + +#### Pre-release pause - stop, go afk, take a break - review time, energy, availability, decide go/no-go -### LEVEL 5 - RELEASED +#### Pre-release tests +Sanity checks: +- appropriate dates/versions in changelogs and release notes (if late in day, watch for time zone issues) +- hledger-install script + - `rg '^HLEDGER(_\w+)?_VERSION' hledger-install/hledger-install.sh` +- binaries' --version output + - `cd ~/Downloads` + - `./hledger --version` + - `./hledger-ui --version` + - `./hledger-web --version` +- binaries' man pages + - `./hledger --man | tail -1` + - `./hledger-ui --man | tail -1` + - `./hledger-web --man | tail -1` + +#### Release tag +- ensure new version has been set first with Shake or bake +- ensure no new commits have been made since push to `github/binaries` +- don't run this in an attempt to make editor tags files +- in the release branch (?): `make tag` #### Github release - in main repo, release branch: - `git push github MA.JOR-branch` or magit `P p` - - wait for CI success (?) - - `git push --tags` or magit `P t` - -- copy text from previous similar release, https://github.com/simonmichael/hledger/releases + - `git push --tags` or magit `P t github` - create new release, https://github.com/simonmichael/hledger/releases/new -- leave release tag unselected for now -- set title (MA.JOR[...]) -- paste & replace with new release notes -- upload CI binaries -- save as draft -- check preview, resolve issues -- edit release -- select release tag (MA.JOR[...]) -- click publish button +- choose release tag +- title: VERSION +- description: + - copy doc/github-release-doc.tmpl.md to editor + - insert latest release notes (minus topmost heading) from site/src/release-notes.md + - replace A-BB, A.BB versions + - copy & paste + - preview, sanity check +- upload platform binary zip files +- Save draft +- (and after successful hackage upload: Publish release) #### Hackage packages in main repo, release branch: @@ -282,24 +306,10 @@ In site repo: ### LEVEL 6 - PUBLISHED -#### hledger-install script -(major/bugfix/fixup release) - -- update `hledger-install/hledger-install.sh` - - HLEDGER_INSTALL_VERSION (release date) - - RESOLVER (same as stack.yaml) - - EXTRA_DEPS (same as stack.yaml) - - hledger official packages (NEW) - - hledger third-party packages (latest version on hackage) -- test ? (won't work until new hledger packages are on hackage) - `cd; bash ~/src/hledger/hledger-install/hledger-install.sh` -- commit: `install: NEW` - #### Install page (major/bugfix/fixup release) In site repo: - - update `install.md` - query-replace OLD -> NEW in - "current hledger release" @@ -309,9 +319,10 @@ In site repo: - cabal install command - query-replace OLD-brightgreen -> OLD-red - only after release binaries are built (preferably after release is published): - update --version outputs (search: hledger --version) - - final output line from `hledger test` (run in terminal for normal speed) + update --version outputs (version, hash, date, but not platform) + - final output line from `hledger test` (run local build and in terminal for normal speed) - Total count from `make functest` + - preview - commit: `install: NEW` #### Update website @@ -375,7 +386,9 @@ In release branch: - `./Shake manuals -c` #### Commit RELEASING.md -- move copy back to RELEASING.md, commit +- move copies back to RELEASING.md, RELEASING.canvas +- re-export RELEASING.png: obsidian > CMD-p > Export as image, don't show logo +- commit #### Push master in main repo, master branch: diff --git a/doc/RELEASING.png b/doc/RELEASING.png index 44eb59a74..ec8863ef9 100644 Binary files a/doc/RELEASING.png and b/doc/RELEASING.png differ