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 2022-09-02 11:54:51 -07:00
parent e2d517a310
commit 3411949313
1 changed files with 101 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
RELEASING.md
View File

@ -79,11 +79,9 @@ Here are some definitions, useful eg when executing or automating release proced
| *master* | The branch named `master` in the hledger repo; the main line of hledger development. Pull requests are usually relative to this. | | *master* | The branch named `master` in the hledger repo; the main line of hledger development. Pull requests are usually relative to this. |
| *release branch* | Branches named `MA.JOR-branch` in the hledger repo, eg `1.25-branch`. Releases and release previews are always made from a release branch. | | *release branch* | Branches named `MA.JOR-branch` in the hledger repo, eg `1.25-branch`. Releases and release previews are always made from a release branch. |
## Procedures
### 0. General tips ## Activities
- Release (or practice releasing) often. Release manager activities/responsibilities include:
- Release responsibilities include:
- **Software** - selecting changes, packages, release dates; coordinating contributions; ensuring release readiness - **Software** - selecting changes, packages, release dates; coordinating contributions; ensuring release readiness
- **Branch Management** - coordinating main and release branch, local and remote repos, CI branches - **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 - **Version Bumping** - choosing and applying new version numbers and related things like tags, github releases, urls, ghc and dep versions, stackage resolvers, everywhere needed
@ -92,24 +90,46 @@ Here are some definitions, useful eg when executing or automating release proced
- **Artifacts** - generating binaries, zip files, github releases etc. - **Artifacts** - generating binaries, zip files, github releases etc.
- **Publishing** - uploading, pushing, making visible, finalising - **Publishing** - uploading, pushing, making visible, finalising
- **Announcing** - various announcement stages and channels - **Announcing** - various announcement stages and channels
- These have complex interdependencies and sequencing constraints. Chunk, separate, routinise, document and automate them as far as possible.
- Don't document in too much detail prematurely.
- Follow RELEASING.md's procedures when helpful, ignore them when not.
- As step 1, save it as RELEASING2.md and make changes there until after release.
- Make things a little better each time through: simpler, more reliable, better documented, more automated, easier, faster, cheaper, higher quality.
- Update [CHANGELOGS](CHANGELOGS.html) early and often, eg during/after a PR, to spread the work.
- Make releases from a release branch, not from master.
- Before making binaries: try to do all possible pre-release-tag steps. (Binaries' --version shows their git hash, and it should match the release tag.)
- Before tagging: make binaries for all platforms, from the same commit.
### 1. Preview release These have complex interdependencies and sequencing constraints. Chunk, separate, routinise, document and automate them as far as possible.
## 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.
- Follow RELEASING.md's procedures if helpful. Update a copy (RELEASING2.md) while releasing.
- The release process continually evolves. 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.
- Before publishing a github release: prepare binaries, release notes, announcements, and tag.
- Before tagging: make binaries for all platforms, from the same commit.
- Before making binaries: do all possible pre-tagging steps and try to get everything finalised. (Binaries' --version shows their git hash, and this should match the release tag.)
## Procedures
### Do a release
- save RELEASING.md as RELEASING2.md
- [check release readiness](#check-release-readiness) - [check release readiness](#check-release-readiness)
- [prepare release branch](#prepare-release-branch) - start making draft binaries: push to `origin/binaries`, resolve failures
- [make binaries](#make-binaries) - update changelogs: see CHANGELOGS.md
- [make release notes](#make-release-notes)
- choose version: MA.JOR, MA.JOR.MINOR, or MA.JOR.MINOR.FIXUP
- [prepare release branch](#prepare-release-branch) (preview/major release)
or cherry pick changes from master (bugfix/fixup release)
- [make new manuals](#make-new-manuals) (major release)
- [update hledger-install](#update-hledger-install) (major/bugfix/fixup release)
- [update install page](#update-install-page) (major/bugfix/fixup release)
- [make announcement](#make-announcement) (major/bugfix release)
- [tag the release](#tag-the-release) - [tag the release](#tag-the-release)
- [push to github](#push-to-github) - [make release binaries](#make-release-binaries)
- [make github release](#make-github-release) - [make github release](#make-github-release) draft
- [update master from release branch](#update-master-from-release-branch) - upload to hackage: `make hackageupload` (major/bugfix/fixup release)
- publish github release
- publish website changes: manuals, release notes, install page
- [announce release](#announce-release) (major/bugfix release)
- move RELEASING2 updates back to RELEASING, commit
- [cherry-pick release branch to master](#cherry-pick-release-branch-to-master)
- bump master to next version: `./Shake setversion A.BB.99` (major release)
#### Check release readiness #### Check release readiness
- master's changelogs are up to date (see [CHANGELOGS](CHANGELOGS.html)) - master's changelogs are up to date (see [CHANGELOGS](CHANGELOGS.html))
@ -124,6 +144,20 @@ Here are some definitions, useful eg when executing or automating release proced
- commit any changes (msg: `tools: shake`) - commit any changes (msg: `tools: shake`)
- appropriate timing, release manager availability - appropriate timing, release manager availability
#### Make release notes
In site repo:
- update `src/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 (bugfix release)
- check preview in vs code
- commit: `relnotes: NEW`
#### Prepare release branch #### Prepare release branch
- `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 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`)
@ -144,65 +178,14 @@ Here are some definitions, useful eg when executing or automating release proced
- `stack exec -- hledger --version`, check version - `stack exec -- hledger --version`, check version
- `stack exec -- hledger help | tail`, check version & date - `stack exec -- hledger help | tail`, check version & date
#### Make binaries #### Make new manuals
- `tools/release bin`
- get all platforms built on the same commit
- download binary artifact zip files
#### Tag the release
- `make tag`
#### Push to github
- `git push origin MA.JOR-branch && git push --tags`
- or in magit: `P p`, `P t`
#### Make github release
- copy text from previous similar release, https://github.com/simonmichael/hledger/releases
- create new release, https://github.com/simonmichael/hledger/releases/new
- select release tag (MA.JOR[...])
- set title (MA.JOR[...])
- paste & replace with new release notes
- upload CI binaries
- save as draft
- github release testing (preview)
- publish
#### Update master from release branch
- switch back to master
- update master changelogs, merging final release changelog entries (see [CHANGELOGS](CHANGELOGS.html))
- cherry-pick other useful changes, such as `;doc: ANNOUNCE`
- after a major release: bump master to new dev version (`./Shake setversion -c A.B.99`)
### 2. Major release
- [make release notes](#make-release-notes)
- [make announcement](#make-announcement)
- [update hledger-install](#update-hledger-install)
- prepare as for [preview release](#1-preview-release)
- [update install page](#update-install-page)
- [add manuals to website](#add-manuals-to-website)
- [announce major release](#announce-major-release)
#### Make release notes
In site repo: In site repo:
- update `src/release-notes.md` - js/site.js: add NEW, update currentrelease
- copy template, uncomment - Makefile: add NEW, two places
- replace date - make snapshot-NEW (after ensuring main repo has been release-tagged)
- replace XX with NEW - commit: `current, makefile, site.js: NEW`
- add new changelog sections, excluding hledger-lib - push
- 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
- commit: `relnotes: NEW`
#### Make announcement
In release branch:
- update `doc/ANNOUNCE` (major release)
- summary, contributors from release notes
- any other edits
- commit: `;doc: announce`
#### Update hledger-install #### Update hledger-install
- update `hledger-install/hledger-install.sh` - update `hledger-install/hledger-install.sh`
@ -230,16 +213,35 @@ In site repo:
- Total count from `make functest` - Total count from `make functest`
- commit: `download: NEW` - commit: `download: NEW`
#### Add new manuals to website #### Make announcement
In site repo: In release branch:
- js/site.js: add NEW, update currentrelease - update `doc/ANNOUNCE` (major release)
- Makefile: add NEW, two places - summary, contributors from release notes
- make snapshot-NEW (after ensuring main repo has been release-tagged) - any other edits
- commit: `current, makefile, site.js: NEW` - commit: `;doc: announce`
- push
#### Announce major release #### Tag the release
- `make tag`
#### Make release binaries
- `tools/release bin`
- get all platforms built on the same commit
- download binary artifact zip files
#### Make github release
- `git push origin MA.JOR-branch && git push --tags` (or magit `P p`, `P t`)
- copy text from previous similar release, https://github.com/simonmichael/hledger/releases
- create new release, https://github.com/simonmichael/hledger/releases/new
- select release tag (MA.JOR[...])
- set title (MA.JOR[...])
- paste & replace with new release notes
- upload CI binaries
- save as draft
- github release testing: preview on github, upload to hackage
- publish
#### Announce release
- pause; take a break afk; check time and energy - pause; take a break afk; check time and energy
- push main repo - push main repo
- push site repo - push site repo
@ -263,17 +265,13 @@ In site repo:
- update last release date on plaintextaccounting.org - update last release date on plaintextaccounting.org
<!-- - toot at https://fosstodon.org/web/accounts/106304084994827771 ? --> <!-- - toot at https://fosstodon.org/web/accounts/106304084994827771 ? -->
### 3. Fixup release #### Cherry-pick release branch to master
- switch to release branch - switch back to master
- cherry pick changes from master - update master changelogs, merging final release changelog entries (see [CHANGELOGS](CHANGELOGS.html))
- proceed as above, with MA.JOR.MINOR.FIXUP - cherry-pick other useful changes, such as `;doc: ANNOUNCE`
- after a major release: bump master to new dev version (`./Shake setversion -c A.B.99`)
### 4. Bugfix release ### Do post-release followup
- switch to release branch
- cherry pick changes from master
- proceed as above, with MA.JOR.MINOR
### 5. After a release
- monitor packaging status, update install page - monitor packaging status, update install page
- docker - expect/merge PR - docker - expect/merge PR
- homebrew - expect badge to update soon - homebrew - expect badge to update soon
@ -283,7 +281,7 @@ In site repo:
- prepare followup releases if needed - prepare followup releases if needed
- update process docs and tools - update process docs and tools
### Packaging ### Update packaging
#### Update homebrew formula #### Update homebrew formula