Skip to content

Latest commit

 

History

History
293 lines (207 loc) · 11.4 KB

RELEASING.md

File metadata and controls

293 lines (207 loc) · 11.4 KB

Releasing

Tips for hledger release managers and maintainers.

Glossary
Full release A release of all the core packages (hledger-lib, hledger, hledger-ui, hledger-web)
Partial release A release of only some of the core packages
Mixed release A release where some of the core packages have different versions (due to previous partial release)
Test release A release that is published on github, but not hackage/stackage. These test the release process (and secondly, generate fresh binaries for early adopters)
hledger repo The hledger git repository, containing the core hledger tools and docs. Official public copy: github.com/simonmichael/hledger
"master" The master branch in the hledger repo; the main line of hledger development
release branch Branches named MAJORVERSION-branch in the hledger repo, eg 1.24-branch. Releases are made from these.
site repo The hledger_website git repository, containing the hledger.org website and additional docs. Usually checked out under the hledger repo as site/.
"site" The master branch in the site repo, used to generate https://hledger.org.
version the 2 or 3-part dotted version number that names a hledger release: MA.JOR or MA.JOR.MINOR.
MAJORVER Just the MA.JOR part, eg 1.24
OLD, NEW Previous and new pending release versions. Examples: 1.24 -> 1.24.1, 1.24.1 -> 1.24.2, 1.24.2 -> 1.25.

2021-12

Starting over, again:

  • All the stuff below the horizontal rule needs review and cleanup already; consider it old.
  • Don't try to write down, let alone automate, every step of releasing; it's too much and too unstable.
  • Practice releasing as often as possible.
  • Keep making things a little better each time through. Simpler, more reliable, easier, faster, cheaper, higher quality.
  • The different aspects of releasing have complex interdependencies and sequencing constraints. Chunk and separate them as far as possible:
    • 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
  • All releases must now be made from a release branch, for uniformity and to avoid mishaps like uploading unreleased code to hackage.

Some next goals

  • Update/consolidate release process docs.
  • Develop a process for making test releases at any time.
  • Establish routine weekly test releases.

Review/update/consolidate:

Phases of release cycle:

0. Dev

Normal development, on master and PR branches.

1. Pre-release

Preparations to make just before a release.

Resolve issues

Review, select, resolve PRs and issues.

Polish changelogs

Complete and polish changelogs.

Plan release

Plan the release number and any extra release-time activities.

2. Release

The sequence of steps to follow when making a release.

Freeze

  • Set version.
  • Finalise changelogs.
  • Generate release notes.
  • Prepare announcement.
  • Tag.
  • Generate CI release binaries.
  • Draft github release.
  • 24 hour release countdown with no changes.
  • If any problems found, return to Pre-release.

Publish

  • Website changes.
    • release notes
    • install page
    • manuals
    • webserver redirects
  • Publish hackage packages.
  • Push tags.
  • Publish github release.
  • Publish website changes.
  • Announce

3. Post-release

Monitor, support, respond.

Release preparation detail

Any time before release

  1. create release branch when needed:
    git branch MAJORVER-branch BRANCHPOINT
    Sometimes when convenient we make major releases on master (adapt the steps below as needed). And make the release branch later, when a minor release becomes necessary, eg:
    git branch 1.22-branch 1.22

  2. update changelogs in master

  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 MAJORVER-branch..master, M-x magit-toggle-buffer-lock, M-x toggle-window-dedicated (C-c D)
      • to: magit, l o master..MAJORVER-branch, M-x magit-toggle-buffer-lock, M-x toggle-window-dedicated
      • ignore commits already seen in previous cherry picking sessions
      • ignore changelog commits / other boring commits ("dev: doc: update changelogs")

    • update changelogs in master (move corresponding change items under pending release heading)

On release day

In master:

  • ./Shake.hs to ensure Shake is current, review commands

  • finalise changelogs, copy each new section (emacs C-x r s a ... b ... c ... d)

In release branch:

  • paste new sections into changelogs

  • ./Shake setversion NEWVER [-c] (first without -c to review, then with -c to commit).

  • ./Shake cmdhelp [-c]

  • ./Shake mandates

  • ./Shake manuals -B [-c] (using up to date doctool versions)

  • make tag (signed annotated tags for each package and the overall release)

  • stack clean && stack install && hledger --version && hledger-ui --version && hledger-web --version to build locally and check version strings

  • push to CI branches to test and to build release binaries

    • git push -f origin master:ci-windows (or magit P -f e origin/ci-windows)
    • git push -f origin master:ci-mac
    • git push -f origin master:ci-linux
    • git push -f origin master:ci-linux-static (at release time only))
    • Tips:
      • build these release binaries at the very last possible moment
      • last commit should be a notable one - not docs only, not beginning with ;

In site repo:

  • update 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 (minor release)
    • check preview in vs code
    • commit: relnotes: NEW

  • update install.md

    • query-replace OLD -> NEW in
      • "current hledger release"
      • CI binaries badges/links, including linux-static-arm32v7 if built
      • "building from source"
      • stack install command
      • cabal install command
    • query-replace OLD-brightgreen -> OLD-red
    • only after release binaries are built (preferably after release is published): update --version outputs (search: hledger --version)
    • final output line from hledger test (run in terminal for normal speed)
    • Total count from make functest
    • commit: download: NEW

In release branch:

  • update doc/ANNOUNCE (major release)
    • summary, contributors from release notes
    • any other edits
    • commit: ;doc: ANNOUNCE

In master:

  • cherry pick useful release branch changes

    • ;doc: ANNOUNCE

  • update hledger-install/hledger-install.sh

    • HLEDGER_INSTALL_VERSION
    • RESOLVER
    • HLEDGER_*_VERSION
    • EXTRA_DEPS

  • wait for CI binaries, https://ci.hledger.org

  • pre-release pause: take a break away from keyboard

Release detail

In release branch:

Post release detail

  • merge/check/update download page changes

    • docker - expect/merge PR
    • homebrew - expect badge to update soon
    • nix - expect make nix-hledger-version to update after a few days, find and update to that commit hash
    • linux distros - once in a while, follow the links & search for newer versions, update

  • support

  • handle issues

  • update procedures, tools, docs

Add major release to website

In site:

  • js/site.js: add NEW, update currentrelease
  • Makefile: add NEW, two places
  • make snapshot-NEW
  • (cd src; rm current; ln -s NEW current)

In hledger.org caddy config:

  • add path and redirs for NEW
  • systemctl reload caddy

On hledger.org:

  • make clean all

Tips

  • During pre/post release phases, update RELEASING.md in a copy, RELEASING2.md, to reduce commit noise and git interference.