Skip to content
Quick links:   Flags   Verbs   Functions   Glossary   Release docs

How to create a new release

This is my checklist for making new releases.

In this example I am using version 6.2.0 to 6.3.0; of course that will change for subsequent revisions.

Release script

Much of the mechanical work below is automated by tools/release.sh, which has three subcommands mirroring the checklist:

  • ./tools/release.sh v6.3.0 pre-release -- version bumps, make dev, commit/push, release tarball, SRPM, and GitHub pre-release (with GitHub's auto-generated release notes) with assets uploaded.
  • ./tools/release.sh v6.3.0 docs -- creates the 6.3.0 docs branch and edits docs/mkdocs.yml. Refuses to run while the GitHub release is still marked pre-release.
  • ./tools/release.sh v6.3.0 afterwork -- flips pkg/version/version.go back to 6.3.0-dev, commits/pushes, and prints the brew/macports/ReadTheDocs reminders with a pre-filled brew bump-formula-pr command.

rpmbuild is mandatory for pre-release (the SRPM is a required release artifact); rpmlint is optional and is run only if installed. The ReadTheDocs admin steps and the flip from pre-release to public remain manual. Each subcommand is idempotent, so a partial run can be re-invoked safely.

If you are running pre-release, do not also do the version-bump / tarball / SRPM / GitHub-release-and-tag steps below by hand first. pre-release does all of that itself, in the order that makes the tag land correctly (version bump commit pushed before the tag is cut). Manually creating the GitHub release/tag before the version-bump commit is pushed reproduces the exact bug called out under "Create the GitHub release tag" below -- the tag gets pinned to whatever commit main was at that moment, forever, even though it looks like --target main. Worse, pre-release's idempotency check only confirms a release exists for the tag; it does not verify the tagged commit actually contains the version bump, so a subsequent pre-release run will not notice or fix a bad tag -- it will just keep uploading assets to it. If this happens, the only fix is to delete the GitHub release and the tag (git push --delete origin vX.Y.Z, plus the local tag) and recreate it pointing at the correct commit.

Manual steps

These are the individual steps pre-release/docs/afterwork automate, kept here as a reference for what each phase actually does (and as a fallback if you need to run a step by hand). Do not run these separately from the script for a release the script is also handling.

  • Update version found in mlr --version and man mlr:

    • Edit pkg/version/version.go from 6.2.0-dev to 6.3.0.
    • Edit miller.spec: Version, and changelog entry
    • Run make dev in the Miller repo base directory
    • The ordering in this makefile rule is important: the first build creates mlr; the second runs mlr to create manpage.txt; the third includes manpage.txt into one of its outputs.
    • Commit and push.

  • If Go version is being updated: edit all three of

    • go.mod
    • .github/workflows/go.yml
    • .github/workflows/release.yml

  • Create the release tarball:

    • make release_tarball
    • This creates miller-6.3.0.tar.gz which we'll upload to GitHub, the URL of which will be in our miller.spec
    • Prepare the source RPM following README-RPM.md.

  • Create the GitHub release tag:

    • If pre-release is handling this release, skip this step -- do not create the release/tag by hand first. See the warning above.
    • Don't forget the v in v6.3.0
    • Write the release notes -- save as a pre-release until below
      • Be sure the commit being used is the (non-main) PR commit containing the new version, or, main after that PR is merged back to main. (Otherwise, the release will be tagging the commit before the changes, and mlr version will not show the new release number.)
    • Thanks to PR 822 which introduces goreleaser there are versions for many platforms auto-built and auto-attached to the GitHub release.
    • Attach the release tarball and SRPM. Double-check assets were successfully uploaded.
    • Publish the release in pre-release mode, until all CI jobs finish successfully. Note that gorelease will create and attach the rest of the binaries.
    • Before marking the release as public, download an executable from among the generated binaries and make sure its mlr version prints what you expect -- else, restart this process. MacOS: xattr -d com.apple.quarantine ./mlr first.
    • Then mark the release as public.

  • Build the release-specific docs:

    • Note: the GitHub release above created a tag v6.3.0 which is correct. Here we'll create a branch named 6.3.0 which is also correct.
    • Create a branch 6.3.0 (not v6.3.0). Locally: git checkout -b 6.3.0, then git push.
    • Edit docs/mkdocs.yml, replacing "Miller Dev Documentation" with "Miller 6.3.0 Documentation". Commit and push.
    • At the Miller Read the Docs admin page, https://readthedocs.org/projects/miller, in the Versions tab, scroll down to Activate a version, then activate 6.3.0.
    • In the Admin tab, in Advanced Settings, set the Default Version and Default Branch both to 6.3.0. Scroll to the end of the page and poke Save.
    • In the Builds tab, if they're not already building, build 6.3.0 as well as latest.
    • Verify that https://miller.readthedocs.io/en/6.3.0 now exists.
    • Verify that https://miller.readthedocs.io/en/latest (with hard page-reload) shows Miller 6.8.0 Documentation in the upper left of the doc pages.

  • Notify:

    • Submit brew pull request; notify any other distros which don't appear to have autoupdated since the previous release (notes below)
    • Similarly for macports: https://github.com/macports/macports-ports/blob/master/textproc/miller/Portfile
    • See also README-versions.md -- distros usually catch up over time but some contacts/pings never hurt to kick-start processes after owners move on from a project they started.
    • Social-media updates.

    • Brew notes:

      • How to submit a version upgrade
      • brew bump-formula-pr --force --strict miller --url https://github.com/johnkerl/miller/releases/download/v6.2.0/miller-6.2.0.tar.gz --sha256 xxx with xxx from shasum -a 256 miller-6.2.0.tar.gz.

  • Afterwork:

    • Edit pkg/version/version.go to change version from 6.3.0 to 6.3.0-dev.
    • make dev
    • Commit and push.