278 lines
8.9 KiB
Markdown
278 lines
8.9 KiB
Markdown
# Releasing
|
|
|
|
<div class=pagetoc>
|
|
<!-- toc -->
|
|
</div>
|
|
|
|
Tips for hledger release managers and maintainers.
|
|
|
|
## 2021-12
|
|
|
|
Starting over, again:
|
|
|
|
- All the stuff below this section needs review and cleanup already; consider it old.
|
|
- Don't try to write down, let alone automate, every step of releasing; it's too much and too unstable.
|
|
- Practice releasing as often as possible.
|
|
- Keep making things a little better each time through. Simpler, more reliable, easier, faster, cheaper, higher quality.
|
|
- The different aspects of releasing have complex interdependencies and sequencing constraints.
|
|
Chunk and separate them as far as possible:
|
|
- **Software** - selecting changes, packages, release dates; coordinating contributions; ensuring release readiness
|
|
- **Branch Management** - coordinating main and release branch, local and remote repos, CI branches
|
|
- **Version Bumping** - choosing and applying new version numbers and related things like tags, github releases, urls, ghc and dep versions, stackage resolvers, everywhere needed
|
|
- **Docs** - command help, manuals, changelogs, release notes, github release notes, install page, install scripts, announcements, process docs
|
|
- **Testing** - local testing, CI testing, extra release-specific testing
|
|
- **Artifacts** - generating binaries, zip files, github releases etc.
|
|
- **Publishing** - uploading, pushing, making visible, finalising
|
|
- **Announcing** - various announcement stages and channels
|
|
|
|
|
|
|
|
## Review/consolidate:
|
|
|
|
## Terminology
|
|
|
|
| | |
|
|
|-------------------------|---------------------------------------------------------------------------------------|
|
|
| *OLD* | previous release version, eg `1.22` or `1.22.1` |
|
|
| *NEW* | new release version, eg `1.22.2` or `1.23` |
|
|
| *MAJORVER* | just the major version part, eg `1.22` or `1.23` |
|
|
| *master (branch)* | `master` branch in the `hledger` repo, ie the main line of development |
|
|
| *release (branch)* | a release branch in the `hledger` repo, eg `1.22-branch` |
|
|
| *site* | `master` branch in the `hledger_website` repo. Usually checked out as `hledger/site`. |
|
|
| | |
|
|
|
|
## Phases of release cycle:
|
|
|
|
|
|
### 0. Dev
|
|
|
|
Normal development, on master and PR branches.
|
|
|
|
|
|
### 1. Pre-release
|
|
|
|
Preparations to make just before a release.
|
|
|
|
#### Resolve issues
|
|
|
|
Review, select, resolve PRs and issues.
|
|
|
|
#### Polish changelogs
|
|
|
|
Complete and polish changelogs.
|
|
|
|
#### Plan release
|
|
|
|
Plan the release number and any extra release-time activities.
|
|
|
|
|
|
### 2. Release
|
|
|
|
The sequence of steps to follow when making a release.
|
|
|
|
#### Freeze
|
|
|
|
- Set version.
|
|
- Finalise changelogs.
|
|
- Generate release notes.
|
|
- Prepare announcement.
|
|
- Tag.
|
|
- Generate CI release binaries.
|
|
- Draft github release.
|
|
- 24 hour release countdown with no changes.
|
|
- If any problems found, return to Pre-release.
|
|
|
|
#### Publish
|
|
|
|
- Website changes.
|
|
- release notes
|
|
- install page
|
|
- manuals
|
|
- webserver redirects
|
|
- Publish hackage packages.
|
|
- Push tags.
|
|
- Publish github release.
|
|
- Publish website changes.
|
|
- Announce
|
|
|
|
### 3. Post-release
|
|
|
|
Monitor, support, respond.
|
|
|
|
|
|
## Release preparation detail
|
|
|
|
### Any time before release
|
|
|
|
1. create release branch when needed:\
|
|
`git branch MAJORVER-branch BRANCHPOINT`\
|
|
Sometimes when convenient we make major releases on master (adapt the steps below as needed).
|
|
And make the release branch later, when a minor release becomes necessary, eg:\
|
|
`git branch 1.22-branch 1.22`
|
|
|
|
1. update changelogs in master
|
|
|
|
1. review changes so far, estimate which packages will be released
|
|
|
|
1. cherry pick changes to release
|
|
- cherry pick release-worthy commits
|
|
- from: magit, `l o MAJORVER-branch..master`, `M-x magit-toggle-buffer-lock`, `M-x toggle-window-dedicated` (`C-c D`)
|
|
- to: magit, `l o master..MAJORVER-branch`, `M-x magit-toggle-buffer-lock`, `M-x toggle-window-dedicated`
|
|
- ignore commits already seen in previous cherry picking sessions
|
|
- ignore changelog commits / other boring commits
|
|
("dev: doc: update changelogs")
|
|
|
|
- update changelogs in master (move corresponding change items under pending release heading)
|
|
|
|
### On release day
|
|
|
|
In master:
|
|
|
|
- `./Shake.hs` to ensure `Shake` is current, review commands
|
|
|
|
- finalise [changelogs](CHANGELOGS.html), copy each new section (emacs `C-x r s a` ... `b` ... `c` ... `d`)
|
|
|
|
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 -B [-c]` (using up to date doctool versions)
|
|
|
|
- `make tag` (signed annotated tags for each package and the overall release)
|
|
|
|
- `stack clean && stack install && hledger --version && hledger-ui --version && hledger-web --version`
|
|
to build locally and check version strings
|
|
|
|
- push to CI branches to test and to build release binaries
|
|
- `git push -f origin master:ci-windows` (or magit `P -f e origin/ci-windows`)
|
|
- `git push -f origin master:ci-mac`
|
|
- `git push -f origin master:ci-linux`
|
|
- `git push -f origin master:ci-linux-static` (at release time only))
|
|
- Tips:
|
|
- build these release binaries at the very last possible moment
|
|
- last commit should be a notable one - not docs only, not beginning with ;
|
|
|
|
In site repo:
|
|
|
|
- update `release-notes.md`
|
|
- 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`
|
|
|
|
- update `install.md`
|
|
- query-replace OLD -> NEW in
|
|
- "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
|
|
- 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)
|
|
- Total count from `make functest`
|
|
- commit: `download: 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`
|
|
|
|
- update `hledger-install/hledger-install.sh`
|
|
- HLEDGER_INSTALL_VERSION
|
|
- RESOLVER
|
|
- HLEDGER_*_VERSION
|
|
- EXTRA_DEPS
|
|
|
|
- wait for CI binaries, https://ci.hledger.org
|
|
|
|
- pre-release pause: take a break away from keyboard
|
|
|
|
## Release detail
|
|
|
|
In release branch:
|
|
|
|
- review status, reflect
|
|
|
|
- `make hackageupload`
|
|
|
|
- push tags: magit `P t origin`
|
|
|
|
- create github release
|
|
- https://github.com/simonmichael/hledger/releases, copy last release's body
|
|
- create new release from NEW tag if CI workflow has failed
|
|
- 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
|
|
- push site download/relnotes updates
|
|
- push master hledger-install update
|
|
- share release notes link, then markdown content, in #hledger chat
|
|
- 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 detail
|
|
|
|
- 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
|
|
|
|
- handle issues
|
|
|
|
- update procedures, tools, docs
|
|
|
|
## Add major release to website
|
|
|
|
In site:
|
|
|
|
- js/site.js: add NEW, update currentrelease
|
|
- Makefile: add NEW, two places
|
|
- make snapshot-NEW
|
|
- (cd src; rm current; ln -s NEW current)
|
|
|
|
In hledger.org caddy config:
|
|
|
|
- add `path` and `redir`s for NEW
|
|
- `systemctl reload caddy`
|
|
|
|
On hledger.org:
|
|
|
|
- make clean all
|
|
|
|
## Tips
|
|
|
|
- During pre/post release phases, update RELEASING.md in a copy,
|
|
RELEASING2.md, to reduce commit noise and git interference.
|
|
|