Release a new version of the factory

Turn what has changed since the last release into a version number, a changelog entry and a tag, then deploy it.

Before you start

• Everything you are releasing is merged, and the suite is green.
• Every change worth telling a reader about has its own line under ## [Unreleased] in the changelog — releasing refuses an empty section, because a version number has to be able to say what it means.
• You have decided which part to bump. This application has no library API, so a user, operator or integration feels exactly three kinds of change:

Before 1.0.0, a breaking change raises MINOR instead of MAJOR, as semantic versioning allows. The reasoning behind the scheme is in Versioning.

Steps

1. Cut it:

.venv/bin/python -m dpf release minor      # or major, patch, or an exact X.Y.Z

This moves the Unreleased section into a new, dated section for the new number, leaves a fresh empty Unreleased above it, and writes the number into VERSION. It refuses, rather than guessing, when the number is not after the current one, when that number is already in the changelog, or when there is nothing under Unreleased to release.

2. Read the diff it printed before doing anything else with it:

git diff VERSION CHANGELOG.md

3. Commit and tag exactly as printed:

git add VERSION CHANGELOG.md && git commit -m "Release X.Y.Z"
git tag -a vX.Y.Z -m "X.Y.Z" && git push origin HEAD vX.Y.Z

4. Deploy it. Shipping by rsync rather than git pull needs the commit written into a BUILD file as well — see Releasing a change.

Check that it worked

• The foot of the sidebar shows the new version, in the application and on every page of the documentation — both read VERSION, and there is nothing else to keep in step.
• python -m dpf --version prints it: dpf X.Y.Z, or dpf X.Y.Z · abcdef0 once a build is known.

If it does not work

• "X.Y.Z is not after Y.Y.Y." You are not bumping from what VERSION actually holds, or typed an exact version that is not higher. Check VERSION before picking the part.
• "X.Y.Z is already in the changelog." Somebody already released this number — bump again, or check whether the release already happened.
• "Nothing under ## [Unreleased]…" Add the missing changelog entries first; see Before you start.

Related

• Versioning — why semantic versioning, and how the documentation stays in step with the code.
• Deploy — shipping the version you just cut.