Release procedure

Release procedure for qbicc

This release process does not affect any branches on the local system. For each step, the corresponding "undo" action is given in case a backtrack is necessary.

Fetch upstream

This gets the latest refs from upstream.

$ git fetch upstream

⚠️ There is no undo for this step; it is non-destructive.

Check out the detached HEAD

$ git checkout --detach upstream/main

Note that the HEAD will be detached even if you do not specify --detach; doing so just prevents a lengthy warning from being displayed.

⚠️ To undo this, git checkout - will put you back into your previous branch.

⚠️ It is much easier to keep track of what is happening if you use a git prompt, like this one.

Update the version

Assuming that the release version will be 0.123.0, follow this procedure:

$ mvn versions:set -DnewVersion=0.123.0

Then, edit docs/README.adoc to change the references to the previous version (e.g. 0.122.0) to reference the new release version 0.123.0 instead.

⚠️ To undo either of these actions, use git reset --hard to restore you to a clean state.

Finally, commit the result:

$ git commit -am 'Prep 0.123.0'

⚠️ To undo this action, reset the branch head using git reset HEAD^.

Create a tag

Create a tag for the release:

$ git tag -a -m 0.123.0 0.123.0

⚠️ To undo this action, use git tag -d 0.123.0.

Build

Build the clean release:

$ mvn clean install -DskipTests

⚠️ This action is (more or less) non-destructive but nevertheless cannot really be undone.

⚠️ Using skipTests is optional but recommended since the commit would already have been tested in CI.

If this build fails, then the release should be abandoned by undoing all previous actions. In this case, be sure to delete the tag to avoid confusion or problems later on.

Deploy

Deploy the release to Maven Central:

$ mvn deploy -DskipTests -Drelease

You will be asked for the passphrase to your GPG key; enter it at the prompt. (TODO: key setup procedure)

⚠️ This action cannot be undone so be certain that you are happy with everything before you execute this step.

TODO: there should be a way to stage the release separately from actually releasing it to Maven Central.

Update upstream/main for next iteration

Check out upstream/main again:

$ git checkout --detach upstream/main

Update the POM versions:

$ mvn versions:set -DnewVersion=0.124.0-SNAPSHOT

And edit the docs/README.adoc again, but again setting the version to the one just released (because this shows on the main page so the commands given should always work). For example, if 0.123.0 was just released, then change references to the previous version (e.g. 0.122.0) to that version (0.123.0).

Commit the result:

$ git commit -am 'Next is 0.124.0'

Dry run push

Make sure the push of main and the tag is clean:

$ git push upstream HEAD:main 0.123.0 --dry-run

Real push

If everything looks OK, do the real push:

$ git push upstream HEAD:main 0.123.0

Cleanup

Don't forget to check out your desired branch again.

Maven deploy fails with module error

The current Maven deployment plugin needs access to some JDK internal classes. In order to facilitate this, in your local checkout create a file named .mvn/jvm.config with the following content:

--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/java.text=ALL-UNNAMED
--add-opens java.desktop/java.awt.font=ALL-UNNAMED

This will prevent the deployment from immediately failing with an error.