;doc: RELEASING updates
This commit is contained in:
Simon Michael
parent
996ccb0ea2
commit
d2a1f17288
@ -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"}
|
||||
]
|
||||
}
|
||||
207
doc/RELEASING.md
207
doc/RELEASING.md
@ -107,16 +107,17 @@ To do a release, start at the bottom of the diagram and work up
|
||||
<!-- source: RELEASING.canvas (Obsidian) -->
|
||||
|
||||
### 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:
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 344 KiB After Width: | Height: | Size: 367 KiB |
Loading…
Reference in New Issue
Block a user