slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f373805668
hledger/RELEASING.md
Simon Michael 9d030a95b6 ;doc: RELEASING: tweaks
2021-08-03 22:45:42 -10:00

4.7 KiB
Raw Blame History

Releasing

Guidance for release managers and maintainers. Some of this might move elsewhere later.

Terminology

  • “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: - 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 bin/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 branch (not in release branches).

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, AUTHOR) on its own line
  • commit: ./Shake changelogs -c

After cherry-picking changes to a release branch: - in the main branch changelogs, move the corresponding changelog items under a pending release heading, creating that when necessary: ``` # LATESTHASH

...CHANGES ONLY IN MASTER...

# NEXTVER unreleased

...CHANGES CHERRYPICKED INTO RELEASE BRANCH...

# LASTVER YYYY-MM-DD
```

At release:

  • do final update/edits; check organisation, wording, formatting, issue links
  • replace “unreleased” with the release date
  • copy the new sections from main changelogs to release branch changelogs

Pre release

  1. create release branch when needed:
    git branch MAJORVER-branch BRANCHPOINT
    Sometimes, we make the major release tag (1.22) on master, and create a release branch (1.22-branch) when there’s a followup minor release:
    git branch 1.22-branch 1.22

  2. update changelogs in main

  3. review changes so far, estimate which packages will be released

  4. cherry pick changes to release

    • cherry pick release-worthy commits
      • from: magit, l o X.Y..master, M-x magit-toggle-buffer-lock, C-x D (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 / other boring commits (“dev: doc: update changelogs”)
    • update changelogs in main (move corresponding change items under pending release heading)

Release

  • finalise 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

Post release

  • merge/check/update download page changes (docker, homebrew, nix, linux distros..)

  • support

  • handle issues

  • update procedures, tools, docs