;doc: RELEASING: updates
This commit is contained in:
Simon Michael
parent
d716aaa5a8
commit
bc2e68cbdb
164
RELEASING.md
164
RELEASING.md
@ -1,58 +1,150 @@
|
||||
# Releasing
|
||||
|
||||
Guidance for release managers and maintainers.
|
||||
Some of this might move elsewhere later.
|
||||
|
||||
Terminology:
|
||||
## Terminology
|
||||
|
||||
- "main" = the `master` branch in the main hledger repo (might be renamed to main in future).
|
||||
- "release" = a release branch in the main hledger repo, such as `1.22`.
|
||||
- "main" / "main branch" = `master` branch in the main hledger repo (might get renamed in future)
|
||||
- "release" / "release branch" = a release branch in the main hledger repo (eg `1.22-branch`)
|
||||
|
||||
## Commits
|
||||
|
||||
**When committing/reviewing:**
|
||||
|
||||
Follow our [commit conventions](CONTRIBUTING.html#commit-messages):
|
||||
- in the summary, use a `feat:`/`imp:`/`fix:` prefix (required for user-visible changes),
|
||||
and/or topic prefixes (`bal:`/`areg:`/`test:`/`doc:`/`lib:`/...)
|
||||
- add a leading `;` to skip wasteful CI builds
|
||||
- add a `!` to indicate breaking/incompatible changes
|
||||
- mention any relevant #issue numbers, usually parenthesised at the end
|
||||
- write the summary and at least the first part of the body, if any,
|
||||
as clear change documentation for the intended audience
|
||||
(users/installers/packagers/developers)
|
||||
|
||||
**When committing/pushing/merging:**
|
||||
- run `tools/commitlint` before push, to check recent commits
|
||||
- or, run it automatically before each commit (`make installcommithook` to configure your local repo)
|
||||
- it also runs in CI on github for pull requests, etc.
|
||||
|
||||
## Changelogs
|
||||
|
||||
Always maintain changelogs in main.
|
||||
Always maintain changelogs in main branch (not in release branches).
|
||||
|
||||
Apply [CONTRIBUTING.md#commit-messages](CONTRIBUTING.html#commit-messages) rules
|
||||
when commiting, pushing, or reviewing/merging pull requests.
|
||||
`tools/commitlint` helps with this, run locally and in CI.
|
||||
**At start of release cycle:**
|
||||
- add the next release heading, with date "unreleased", above last release heading:
|
||||
|
||||
Use `./Shake changelogs` to update them from recent commit messages.
|
||||
|
||||
## Minor release
|
||||
|
||||
Checklist:
|
||||
|
||||
1. create release branch if none\
|
||||
`git branch RELEASEBRANCH RELEASETAG`\
|
||||
`git branch 1.22-branch 1.22`
|
||||
|
||||
1. update main changelogs
|
||||
- `./Shake changelogs`
|
||||
- do at least basic editing - drop things, move things
|
||||
- `./Shake changelogs -c`
|
||||
|
||||
1. review changes so far, estimate which packages will be released
|
||||
|
||||
1. add "unreleased" minor release heading in main changelogs, immediately above previous release heading
|
||||
```
|
||||
# LATESTHASH
|
||||
|
||||
...
|
||||
...CHANGES...
|
||||
|
||||
# X.Y.1 unreleased <- new heading
|
||||
# NEXTVER unreleased <- ADD
|
||||
|
||||
# X.Y YYYY-MM-DD
|
||||
# LASTVER YYYY-MM-DD
|
||||
```
|
||||
|
||||
**Frequently**, especially after merging changes, and before cherry picking into release branch:
|
||||
|
||||
- dry run: `./Shake changelogs -n`
|
||||
- add new changes: `./Shake changelogs`
|
||||
- edit
|
||||
- drop things
|
||||
- move things
|
||||
- Add headings: Features, Improved, Fixes
|
||||
- rewrite things
|
||||
- format ([#ISSUE](https://github.com/simonmichael/hledger/issues/), AUTHOR) on its own line
|
||||
- commit: `./Shake changelogs -c`
|
||||
|
||||
**After cherry-picking** changes to a release branch:
|
||||
- move the corresponding changelog items under the pending release heading.
|
||||
|
||||
**At release:**
|
||||
|
||||
- do final update/edits; check organisation, wording, formatting, issue links
|
||||
- replace "unreleased" with the date in the pending release heading
|
||||
- copy the new release sections from main changelogs to release branch changelogs
|
||||
|
||||
## Pre release
|
||||
|
||||
1. create release branch when needed:\
|
||||
`git branch MAJORVER-branch BRANCHPOINT`\
|
||||
When convenient, the first major release can be tagged on master (`1.22`),
|
||||
and the release branch (`1.22-branch`) gets created when there's a followup minor release:\
|
||||
`git branch 1.22-branch 1.22`
|
||||
|
||||
1. update changelogs in main
|
||||
|
||||
1. review changes so far, estimate which packages will be released
|
||||
|
||||
1. cherry pick changes to release
|
||||
1. always update main changelogs first
|
||||
2. cherry pick minor-release-worthy commits
|
||||
- cherry pick minor-release-worthy commits
|
||||
- from: magit, `l o X.Y..master`, `M-x magit-toggle-buffer-lock`, `C-x D`
|
||||
(`M-x toggle-window-dedicated`)
|
||||
(`M-x toggle-window-dedicated`)
|
||||
- to: magit, `l o master..X.Y`, `M-x magit-toggle-buffer-lock`, `C-x D`
|
||||
- ignore commits already seen in previous cherry picking sessions
|
||||
- ignore changelog commits ("dev: doc: update ...")
|
||||
3. in main changelogs, move corresponding change items under minor release heading
|
||||
- ignore changelog commits / other boring commits
|
||||
("dev: doc: update changelogs")
|
||||
|
||||
1. finalise release
|
||||
- add date to minor release heading in main changelogs
|
||||
- copy the minor release section from main changelogs to release changelogs
|
||||
1. in changelogs in main, move corresponding change items under pending release heading
|
||||
|
||||
## Release
|
||||
|
||||
- finalise [changelogs](#changelogs) in main,
|
||||
copy to changelogs in release branch
|
||||
|
||||
- `./Shake.hs` to update `Shake` and review release tasks
|
||||
|
||||
- `./Shake setversion VER [-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]`
|
||||
|
||||
- `make tag`
|
||||
|
||||
- `make hackageupload`
|
||||
|
||||
- push tags: magit `P t`
|
||||
|
||||
- push to CI branches to test & generate binaries
|
||||
- magit `P -f e origin/ci-windows`
|
||||
- ... `origin/ci-mac`
|
||||
- ... `origin/ci-linux-static`
|
||||
- ... `origin/ci-linux-static-arm32`
|
||||
|
||||
- in site: update `download.md`
|
||||
|
||||
- in site: update `relnotes.md`
|
||||
- copy template
|
||||
- add new changelog sections, omitting hledger-lib
|
||||
- add summary
|
||||
- add contributors
|
||||
|
||||
- update `doc/ANNOUNCE`
|
||||
- summary/contributors from release notes
|
||||
|
||||
- create github release
|
||||
- tag VER, title VER, body similar to previous release
|
||||
- at https://ci.hledger.org download each CI branch artifact when ready, to ~/Downloads/hledger-VER/
|
||||
- drag artifacts into github draft release
|
||||
- publish release
|
||||
|
||||
- announce
|
||||
- send ANNOUNCE to hledger@googlegroups.com, haskell-cafe@googlegroups.com
|
||||
- link release notes/summary in #hledger:matrix.org, #hledger:libera.chat
|
||||
- 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..)
|
||||
|
||||
- support
|
||||
|
||||
- handle issues
|
||||
|
||||
- update procedures, tools, docs
|
||||
|
||||
Loading…
Reference in New Issue
Block a user