mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-19 18:29:36 +03:00
doc: RELEASING: updates
This commit is contained in:
Simon Michael
parent
38cb53d4f8
commit
3e4f5f0417
204
RELEASING.md
204
RELEASING.md
@ -79,37 +79,57 @@ 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. |
|
||||
| *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. |
|
||||
|
||||
|
||||
## Activities
|
||||
Release manager activities/responsibilities include:
|
||||
- **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
|
||||
|
||||
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
|
||||
|
||||
### 0. General tips
|
||||
- Release (or practice releasing) often.
|
||||
- Release responsibilities include:
|
||||
- **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
|
||||
- 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
|
||||
### Do a release
|
||||
- save RELEASING.md as RELEASING2.md
|
||||
- [check release readiness](#check-release-readiness)
|
||||
- [prepare release branch](#prepare-release-branch)
|
||||
- [make binaries](#make-binaries)
|
||||
- start making draft binaries: push to `origin/binaries`, resolve failures
|
||||
- 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)
|
||||
- [push to github](#push-to-github)
|
||||
- [make github release](#make-github-release)
|
||||
- [update master from release branch](#update-master-from-release-branch)
|
||||
- [make release binaries](#make-release-binaries)
|
||||
- [make github release](#make-github-release) draft
|
||||
- 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
|
||||
- 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`)
|
||||
- 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
|
||||
- `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`)
|
||||
@ -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 help | tail`, check version & date
|
||||
|
||||
#### Make binaries
|
||||
- `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
|
||||
#### Make new manuals
|
||||
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`
|
||||
|
||||
#### Make announcement
|
||||
In release branch:
|
||||
|
||||
- update `doc/ANNOUNCE` (major release)
|
||||
- summary, contributors from release notes
|
||||
- any other edits
|
||||
- commit: `;doc: announce`
|
||||
- js/site.js: add NEW, update currentrelease
|
||||
- Makefile: add NEW, two places
|
||||
- make snapshot-NEW (after ensuring main repo has been release-tagged)
|
||||
- commit: `current, makefile, site.js: NEW`
|
||||
- push
|
||||
|
||||
#### Update hledger-install
|
||||
- update `hledger-install/hledger-install.sh`
|
||||
@ -230,16 +213,35 @@ In site repo:
|
||||
- Total count from `make functest`
|
||||
- commit: `download: NEW`
|
||||
|
||||
#### Add new manuals to website
|
||||
In site repo:
|
||||
#### Make announcement
|
||||
In release branch:
|
||||
|
||||
- js/site.js: add NEW, update currentrelease
|
||||
- Makefile: add NEW, two places
|
||||
- make snapshot-NEW (after ensuring main repo has been release-tagged)
|
||||
- commit: `current, makefile, site.js: NEW`
|
||||
- push
|
||||
- update `doc/ANNOUNCE` (major release)
|
||||
- summary, contributors from release notes
|
||||
- any other edits
|
||||
- commit: `;doc: announce`
|
||||
|
||||
#### 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
|
||||
- push main repo
|
||||
- push site repo
|
||||
@ -263,17 +265,13 @@ In site repo:
|
||||
- update last release date on plaintextaccounting.org
|
||||
<!-- - toot at https://fosstodon.org/web/accounts/106304084994827771 ? -->
|
||||
|
||||
### 3. Fixup release
|
||||
- switch to release branch
|
||||
- cherry pick changes from master
|
||||
- proceed as above, with MA.JOR.MINOR.FIXUP
|
||||
#### Cherry-pick release branch to master
|
||||
- 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`)
|
||||
|
||||
### 4. Bugfix release
|
||||
- switch to release branch
|
||||
- cherry pick changes from master
|
||||
- proceed as above, with MA.JOR.MINOR
|
||||
|
||||
### 5. After a release
|
||||
### Do post-release followup
|
||||
- monitor packaging status, update install page
|
||||
- docker - expect/merge PR
|
||||
- homebrew - expect badge to update soon
|
||||
@ -283,7 +281,7 @@ In site repo:
|
||||
- prepare followup releases if needed
|
||||
- update process docs and tools
|
||||
|
||||
### Packaging
|
||||
### Update packaging
|
||||
|
||||
#### Update homebrew formula
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user