hledger/RELEASING.md

# Releasing

<div class=pagetoc>
<!-- toc -->
</div>

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](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 `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](https://github.com/simonmichael/hledger/issues/), 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`

1. update changelogs in main

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

1. 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](#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