slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: RELEASING updates

Browse Source
This commit is contained in:
Simon Michael 2023-04-07 14:33:11 -10:00
parent 996ccb0ea2
commit d2a1f17288
3 changed files with 120 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/RELEASING.canvas
View File

@ -1,7 +1,5 @@
{ {
"nodes":[ "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 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":"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"}, {"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 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 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 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 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":"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"}, {"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":"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":"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":"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 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 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 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 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":"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":"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":[ "edges":[
{"id":"1cbe2796fa62185f","fromNode":"52d90724c458c2d2","fromSide":"bottom","toNode":"2d971da3a664c356","toSide":"top"}, {"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":"c15e04d54adbe3b7","fromNode":"cd072c3e5f37fc77","fromSide":"bottom","toNode":"887e2b1b907d0ac9","toSide":"top"},
{"id":"70b80ea2ea092fd0","fromNode":"5fa590b519f60b9b","fromSide":"bottom","toNode":"187d7edfa7e9f024","toSide":"top"}, {"id":"70b80ea2ea092fd0","fromNode":"5fa590b519f60b9b","fromSide":"bottom","toNode":"187d7edfa7e9f024","toSide":"top"},
{"id":"83ace9eece04a0c9","fromNode":"42f027c1822c2021","fromSide":"bottom","toNode":"05062529ce2b5d9a","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"}
] ]
} }

207
doc/RELEASING.md
View File

@ -107,16 +107,17 @@ To do a release, start at the bottom of the diagram and work up
<!-- source: RELEASING.canvas (Obsidian) --> <!-- source: RELEASING.canvas (Obsidian) -->
### General tips ### General tips
- Update changelogs early and often, eg during/after a PR, to spread the work. - Release (or practice releasing) often to improve the process.
See also [CHANGELOGS](CHANGELOGS.html). - Use and continually update RELEASING.md and RELEASING.canvas.
- Release (or practice releasing) often. - 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.)
- 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.
- Don't document procedures in too much detail / prematurely. - 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 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. - `make`, `./Shake` and `./bake`.
- Use the tools/release script. - Update changelogs early and often, eg during/after a PR, to spread the work.
- Binaries' --version shows their git hash and build date; these should match the release tag and release date. 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 ### LEVEL 1 - DEV
@ -129,6 +130,14 @@ To do a release, start at the bottom of the diagram and work up
### LEVEL 2 - TEST ### 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 #### Up-to-date cabal files
- `./Shake cabalfiles` - `./Shake cabalfiles`
- if there are changes, `./Shake cabalfiles -c` - 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` - if there are changes, `./Shake manuals -c`
#### Up-to-date changelogs #### Up-to-date changelogs
in main repo, master branch: In main repo, master branch:
- `./Shake changelogs` - `./Shake changelogs`
- clean up the five `CHANGES.md`s - clean up the five `CHANGES.md`s
- `./Shake changelogs -c` - `./Shake changelogs -c`
See also [CHANGELOGS](CHANGELOGS.md). See [CHANGELOGS](CHANGELOGS.md).
#### Passing tests and CI #### Passing tests and CI
- `make functest` - local tests, mimicking CI
- `make test` - `make test`
- `make bench` ? - `make doctest`
- `make haddocktest` ? - `make haddocktest`
- CI tests in github main repo - 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 - push to a PR, wait for green
- or push to `simon` branch, wait for green at http://ci.hledger.org - or push to `simon` branch, wait for green at http://ci.hledger.org
- or `tools/push` (pushes to `simon`, then to `master`) - 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 ### LEVEL 3 - RELEASE DOCS
#### Copy RELEASING.md 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.
- copy of RELEASING.md to RELEASING_.md; make updates in the copy
#### Release branch
Bugfix/fixup release:
- switch to release branch, cherry pick changes from master
#### Prepare release branch
Preview/major release: Preview/major release:
- `PAUSE=1 ECHO=1 ./bake prep MA.JOR[.99.PREVIEWNUM]` (eg 1.24.99.1 for 1.25 preview 1)
- `PAUSE=1 ECHO=1 tools/release prep MA.JOR[.99.PREVIEWNUM]` (eg 1.24.99.1 for 1.25 preview 1)
(XXX seems to go wrong without PAUSE`) (XXX seems to go wrong without PAUSE`)
- clean up changelogs, amend changelogs commit (see also [CHANGELOGS](CHANGELOGS.html)) - clean up changelogs, amend changelogs commit (see also [CHANGELOGS](CHANGELOGS.html))
- cherry pick changes from master (if needed) - cherry pick changes from master (if needed)
@ -194,76 +194,100 @@ Preview/major release:
- `stack build --test` - `stack build --test`
- `make functest` - `make functest`
Bugfix/fixup release:
- cherry pick changes from master
#### Release version number #### Release version number
- choose new version (NEW): MA.JOR, MA.JOR.MINOR, or MA.JOR.MINOR.FIXUP - Choose new version (NEW): MA.JOR, MA.JOR.MINOR, or MA.JOR.MINOR.FIXUP
- on release branch do `./Shake setversion -c NEW` - In release branch do `./Shake setversion -c NEW`
#### Release changelogs #### Release changelogs
- add release version/date headings manually (or fix `bake prep`, then clean up manually)
#### Release notes #### 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` ### LEVEL 4 - RELEASE BINARIES
- 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 READY #### Release build tests
#### 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
- touch/change Version.hs to encourage recompilation - touch/change Version.hs to encourage recompilation
- `stack build` - `stack build`
- `stack exec -- hledger --version`, check version, hash, release date, no '+' - `stack exec -- hledger --version`, check version, hash, release date, no '+'
- `stack exec -- hledger help | tail`, check version, month matches release - `stack exec -- hledger help | tail`, check version, month matches release
#### Release tag #### Platform CI tests
- ensure new version has been set with Shake setversion ! Multi-platform CI tests:
- `make tag` - push to `github/binaries` (or `./bake bin`)
- resolve failures
- wait for green on all platforms
#### Pre-release tests #### Release binaries
- appropriate dates in: changelogs, release notes, --version output, man pages, hledger-install script 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 - stop, go afk, take a break
- review time, energy, availability, decide go/no-go - 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 #### Github release
- in main repo, release branch: - in main repo, release branch:
- `git push github MA.JOR-branch` or magit `P p` - `git push github MA.JOR-branch` or magit `P p`
- wait for CI success (?) - `git push --tags` or magit `P t github`
- `git push --tags` or magit `P t`
- copy text from previous similar release, https://github.com/simonmichael/hledger/releases
- create new release, https://github.com/simonmichael/hledger/releases/new - create new release, https://github.com/simonmichael/hledger/releases/new
- leave release tag unselected for now - choose release tag
- set title (MA.JOR[...]) - title: VERSION
- paste & replace with new release notes - description:
- upload CI binaries - copy doc/github-release-doc.tmpl.md to editor
- save as draft - insert latest release notes (minus topmost heading) from site/src/release-notes.md
- check preview, resolve issues - replace A-BB, A.BB versions
- edit release - copy & paste
- select release tag (MA.JOR[...]) - preview, sanity check
- click publish button - upload platform binary zip files
- Save draft
- (and after successful hackage upload: Publish release)
#### Hackage packages #### Hackage packages
in main repo, release branch: in main repo, release branch:
@ -282,24 +306,10 @@ In site repo:
### LEVEL 6 - PUBLISHED ### 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 #### Install page
(major/bugfix/fixup release) (major/bugfix/fixup release)
In site repo: In site repo:
- update `install.md` - update `install.md`
- query-replace OLD -> NEW in - query-replace OLD -> NEW in
- "current hledger release" - "current hledger release"
@ -309,9 +319,10 @@ In site repo:
- cabal install command - cabal install command
- query-replace OLD-brightgreen -> OLD-red - query-replace OLD-brightgreen -> OLD-red
- only after release binaries are built (preferably after release is published): - only after release binaries are built (preferably after release is published):
update --version outputs (search: hledger --version) update --version outputs (version, hash, date, but not platform)
- final output line from `hledger test` (run in terminal for normal speed) - final output line from `hledger test` (run local build and in terminal for normal speed)
- Total count from `make functest` - Total count from `make functest`
- preview
- commit: `install: NEW` - commit: `install: NEW`
#### Update website #### Update website
@ -375,7 +386,9 @@ In release branch:
- `./Shake manuals -c` - `./Shake manuals -c`
#### Commit RELEASING.md #### 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 #### Push master
in main repo, master branch: in main repo, master branch:

BIN
doc/RELEASING.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 344 KiB

After

Width:  |  Height:  |  Size: 367 KiB