Releasing PLC4X Build-Tools

According to SemVer, we have: Major, Minor and Bugfix releases.

For each new Major and Minor release we create a new branch at the beginning of a code-freeze phase.

So if currently the project version in develop is {0.13.0-SNAPSHOT}, we create a branch release/{code-generation-short-version}.

When creating the branch is exactly the moment in which the version in develop is incremented to the next minor version.

This can and should be automated by the maven-release-plugin.

Per default the plugin will ask for the working copy version during the build execution. This is the version the develop branch will be changed to.

Per default the plugin suggests the next bugfix version as working version, however we want it to use the next minor version. So in case of preparing the release branch for {0.13.0-SNAPSHOT} the command would be the following:

The plugin will then aks for the version:

Where the suggested default is manually overridden.

This step now should perform quite quickly as no build and no tests are involved.

However in the end the versions of the develop branch are updated and a new releases/code-generation/{code-generation-short-version} branch is created.

Now is a good time to add a new section to the RELEASE_NOTES document for the new SNAPSHOT version.

Here comes a template:

After that please remove the (Unreleased) from the following section, as we are currently working on its release.

Also be sure to do a quick full-text-search to check if the version was updated correctly everywhere.

Now usually comes a phase in which last tests and checks should be performed.

If any problems are found they, have to be fixed in the release branch.

Changes should either be re applied in develop or cherry-picked, however merging things back can cause a lot of problems, and we no longer have the same versions.

Before you start preparing the release, it is important to manually make the RELEASE_NOTES reflect the version we are planning on releasing.

So be sure to remove the (Unreleased) and SNAPSHOT from the version.

As especially when switching a lot between different branches, it is recommended to do a clean checkout of the repository. Otherwise, a lot of directories can be left over, which would be included in the source-release zip. In order to prepare a release-candidate, the first step is switching to the corresponding release-branch.

After that, the following command will to all preparation steps for the release:

In general the plugin will now ask you 3 questions:

Usually for 1 and 3 the defaults are just fine, make sure the tag name is correct as this usually is different.

However, it is important to check that nowhere else SNAPSHOT versions are referenced.

What the plugin now does, is automatically to execute the following operations:

However, this just prepared the git repository for the release, we have to perform the release to produce and stage the release artifacts.

Please verify the git repository at: https://gitbox.apache.org/repos/asf?p=plc4x-build-tools.git is in the correct state. Please select the release branch and verify the commit log looks similar to this

It is important that the commit with the message "[maven-release-plugin] prepare release releases/code-generation/{0.13.0-SNAPSHOT}" is tagged with the release tag (in this case releases/code-generation/{0.13.0-SNAPSHOT})

If you check the commit itself, it should mainly consist of version updates like this:

The root pom has a few more changes, but in general this should be what you are seeing.

After that should come a second commit:

This now updates the versions again, but this time from the release version to the one we selected for the next development iteration (in this case {code-generation-bugfix-version}-SNAPSHOT)

If something goes wrong, you can always execute:

And it will change the versions back and commit and push things.

However, it will not delete the tag in GIT (locally and remotely). So you have to do that manually or use a different tag next time.

This is done by executing another goal of the maven-release-plugin:

This executes automatically as all information it requires is located in the release.properties file the prepare-goal prepared.

The first step is that the perform-goal checks out the previously tagged revision into the root modules target/checkout directory. Here it automatically executes a maven build (You don’t have to do this, it’s just that you know what’s happening):

As the apache-release profile is activated, this builds and tests the project as well as creates the JavaDocs, Source packages and signs each of these with your PGP key.

As this time the build is building with release versions, Maven will automatically choose the release url for deploying artifacts.

The way things are set up in the apache parent pom, is that release artifacts are deployed to a so-called staging repository.

You can think of a staging repository as a dedicated repository created on the fly as soon as the first artifact comes in.

After the build you will have a nice and clean Maven repository at https://repository.apache.org/ that contains only artifacts from the current build.

After the build it is important to log in to Nexus at https://repository.apache.org/, select Staging Repositories and find the repository with the name: orgapacheplc4x-{somenumber}.

Select that and click on the Close button.

Now Nexus will do some checks on the artifacts and check the signatures.

As soon as it’s finished, we are done on the Maven side and ready to continue with the rest of the release process.

A release build also produces a so-called source-assembly zip.

This contains all sources of the project and will be what’s actually the release from an Apache point of view and will be the thing we will be voting on.

This file will also be signed and SHA512 hashes will be created.

Each new release and release-candidate has to be staged in the Apache SVN under:

https://dist.apache.org/repos/dist/dev/plc4x/

The directory structure of this directory is as follows:

I usually prepare exactly the same directory structure, starting with the {0.13.0-SNAPSHOT} locally and then just import everything using the following command:

The KEYS file contains the PGP public key which belongs to the private key used to sign the release artifacts.

If this is your first release be sure to add your key to this file. For the format have a look at the file itself. It should contain all the information needed.

Be sure to stage exactly the README and RELEASE_NOTES files contained in the root of your project. Ideally you just copy them there from there.

The three -source-release.zip artifacts should be located in the directory: code-generation/target/checkout/code-generation/target

So, after committing these files to SVN, you are ready to start the vote.

After staging the release candidate in the Apache SVN, it is time to actually call out the vote.

For this we usually send two emails. The following would be the one used to do our first TLP release:

As it is sometimes to do the vote counting, if voting and discussions are going on in the same thread, we send a second email:

Now we have to wait 72 hours till we can announce the result of the vote.

This is an Apache policy to make it possible for anyone to participate in the vote, no matter where that person lives and not matter what weekends or public holidays might currently be.

The vote passes, if at least 3 +1 votes are received and more +1 are received than -1.

After the 72-our minimum wait period is over, and we have fulfilled the requirement of at least 3 +1 votes and more +1 than -1, a final reply is sent to the vote thread with a prefix of [RESULT] in the title in which the summary of the vote is presented in an aggregated form.

As soon as the votes are finished, and the results were in favor of a release, the staged artifacts can be released. This is done by moving them inside the Apache SVN.

This will make the release artifacts available and will trigger them being copied to mirror sites.

This is also the reason why you should wait at least 24 hours before sending out the release notification emails.

As a lot of mirrors are serving our releases, it is the Apache policy to clean old releases from the repo if newer versions are released.

This can be done like this:

After this, https://dist.apache.org/repos/dist/release/plc4x should only contain the latest release directory.

The probably simplest part is releasing the Maven artifacts.

In order to do this, the release manager logs into Nexus at https://repository.apache.org/, selects the staging repository and clicks on the Release button.

This will move all artifacts into the Apache release repository and delete the staging repository after that.

All release artifacts released to the Apache release repo, will automatically be synced to Maven central.

The `release branch should always point to the last released version. This has to be done with git

When there are conflicts it could help to use the theirs merge strategy, i.e.,

Possibly a manual conflict resolution has to be done afterwards. After that, changes need to be pushed.

In contrast to main releases of PLC4X we won’t do any JIRA version updates, updating of the download page or notifying of the world email to announce@apache.org

So now you’re done. Congrats!