;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
|
# Releasing
|
||||||
|
|
||||||
Guidance for release managers and maintainers.
|
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).
|
- "main" / "main branch" = `master` branch in the main hledger repo (might get renamed in future)
|
||||||
- "release" = a release branch in the main hledger repo, such as `1.22`.
|
- "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
|
## 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
|
**At start of release cycle:**
|
||||||
when commiting, pushing, or reviewing/merging pull requests.
|
- add the next release heading, with date "unreleased", above last release heading:
|
||||||
`tools/commitlint` helps with this, run locally and in CI.
|
|
||||||
|
|
||||||
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
|
# 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. cherry pick changes to release
|
||||||
1. always update main changelogs first
|
- cherry pick minor-release-worthy commits
|
||||||
2. cherry pick minor-release-worthy commits
|
|
||||||
- from: magit, `l o X.Y..master`, `M-x magit-toggle-buffer-lock`, `C-x D`
|
- 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`
|
- 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 commits already seen in previous cherry picking sessions
|
||||||
- ignore changelog commits ("dev: doc: update ...")
|
- ignore changelog commits / other boring commits
|
||||||
3. in main changelogs, move corresponding change items under minor release heading
|
("dev: doc: update changelogs")
|
||||||
|
|
||||||
1. finalise release
|
1. in changelogs in main, move corresponding change items under pending release heading
|
||||||
- add date to minor release heading in main changelogs
|
|
||||||
- copy the minor release section from main changelogs to release changelogs
|
## 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