Release Process

Clocker Releases

This describes the process to follow for generating a Clocker release. Once we have code in master that we want to turn into a release, the following process can be followed to create the required distribution and other artifacts on the various repositories.

The final release will consist of:

1. Code in release/X.Y.x branch updated with correct Clocker and other versions, and tagged as vX.Y.Z.
2. Clocker brooklyn-clocker-dist.tar.gz archive and brooklyn-clocker-dist.tar.gz.asc signature on the releases/ page.
3. Clocker Jar files pushed to Sonatype and to Cloudsoft Artifactory.
4. Docker Hub clockercentral/clocker image created with tag X.Y.Z.
5. Clocker master branch X.Y.0-SNAPSHOT version incremented.
6. Clocker README.md files updated to point at latest artifact short URLs.

Current Version

The current Clocker version is 1.1.0-SNAPSHOT on master and 1.1.0-PREVIEW.20160215 on the release/1.1.x branch.

You can download the distribution archive at the releases page, or use Docker to run the latest image:

% docker run -v ~/.brooklyn:/root/.brooklyn -v ~/.ssh:/root/.ssh -P \
    -d clockercentral/clocker:1.1.0-PREVIEW.20160215

Release Process

First, determine the version number you will be using for this release. We use semantic versioning for Clocker. For a full release, this will be something like X.Y.Z with whatever numbers are required. Generally, major releases have the form X.Y.0 and then minor patches and hotfixes will increment the last number. A preview or temporary release would have -PREVIEW.YYYYMMDD or -TMP.NNNN appended to the version string, where YYYYMMDD is the current date and NNNN is a zero-padded integer. The master branch should always have a version that looks like X.Y.0-SNAPSHOT and if a full (i.e. not preview or temporary) release is being made, the release/X.Y.x branch will then use X.Y.0 as the first version, incrementing the minor version number Z as required for further releases, and master will then have Y incremented by one in its -SNAPSHOT version. For preview and temporary releases, the master version should be left unchanged.

Possible version numbers are:

• 1.2.0
• 1.2.12
• 1.3.0-PREVIEW.20161112
• 1.3.1-TMP.0001

Create The Release Branch

First, select the release branch to use. These are wildcarded based on the minor version number; Clocker version 1.1.0 would use the release/1.1.x branch, version 1.3.4 would use release/1.3.x and so on. If the branch does not exist, you should create it. For new branches, you will also need to make some changes to dist/Dockerfile and clocker.bom to use the Cloudsoft repository for releases, otherwise skip this step.. Change these files as follows:

The clocker.bom File

Change the lines after brooklyn.libraries from:

  - "https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=io.brooklyn.clocker&a=brooklyn-clocker-patches&v=1.1.0-SNAPSHOT" # CLOCKER_VERSION

to:

  - "http://ccweb.cloudsoftcorp.com/maven/libs-release-local/io/brooklyn/clocker/brooklyn-clocker-patches/1.1.0-SNAPSHOT/brooklyn-clocker-patches-1.1.0-SNAPSHOT.jar" # CLOCKER_VERSION

The dist/Dockerfile File

Change the wget line of the RUN command from:

RUN wget --no-check-certificate https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots\&g=io.brooklyn.clocker\&a=brooklyn-clocker-dist\&v=1.1.0-SNAPSHOT\&c=dist\&e=tar.gz -O /brooklyn-clocker-dist.tar.gz ;

to:

RUN wget --no-check-certificate http://ccweb.cloudsoftcorp.com/maven/libs-release-local/io/brooklyn/clocker/brooklyn-clocker-dist/1.1.0-SNAPSHOT/brooklyn-clocker-dist-1.1.0-SNAPSHOT-dist.tar.gz -O /brooklyn-clocker-dist.tar.gz ; \

Do not change the version number in either of these files, it should remain the same -SNAPSHOT string as master for now. Simply commit the changes as follows:

% git add --all
% git commit -m "Updated Dockerfile and clocker.bom to point to Cloudsoft Artifactory"
...

You should now be using the checked-out release/<version> branch. Make sure you have the latest code from master:

% git pull --rebase origin master
...

Set The Release Version

The version number for the release selected above should be set, using the Brooklyn change-version.sh script. This can be found in the brooklyn-dist repository, here: https://github.com/apache/brooklyn-dist/blob/master/release/change-version.sh. You may also need to change the version used for Brooklyn, and other projects, which can be done with the same script. These version changes should be added as a single commit.

For example, if the current version is 1.2.0-SNAPSHOT and you are making a new 1.2.0 release, using the release/1.2.x branch, execute the following commands:

% change-version.sh CLOCKER 1.2.0-SNAPSHOT 1.2.0
...
% change-version.sh BROOKLYN 0.10.0-SNAPSHOT 0.9.0
...
% change-version.sh ADVANCED_NETWORKING 0.10.0-SNAPSHOT 0.9.0
...
% find . -name "*.bak" -delete
% git add --all
% git commit -m "Version 1.2.0"
...

Once you are have done this, tag the branch with the version, using the tag vX.Y.Z or the equivalent (with v prefixed) as follows:

% git tag v1.2.0

On the master branch, you should update the -SNAPSHOT version if required:

% change-version.sh CLOCKER 1.2.0-SNAPSHOT 1.3.0-SNAPSHOT
...
% find . -name "*.bak" -delete
% git add --all
% git commit -m "Version 1.3.0-SNAPSHOT"
...

Update the README.md File

Using <git.io>, create a new short URL for the Clocker distribution archive download link in the README.md file.

Build The Release

Now, build the Clocker code as usual, to confirm that there are no issues:

% mvn clean install
...

Assuming this is successful, you can now deploy the artifacts to external Maven repositories. The Cloudsoft repository is used for releases (with the libs-release-local id) and also Sonatype open source repositories for both -SNAPSHOT and release versions. However, note that to deploy a release version (that is, non -SNAPSHOT) to Sonatype requires a login to their Nexus repository to be configured, and this process is not covered here. You must also be configured to sign artifacts using GPG, with the maven-gpg-plugin. There is external documentation available to help with this setup.

Deploy the artifacts to the Cloudsoft Artifactory repository as follows:

% mvn clean deploy -Dbrooklyn.deployTo=cloudsoft -DskipTests
...

If you wish to deploy to the Sonatype OSS release repository, see the documentation above.

On the master branch, deploy the updated -SNAPSHOT artifacts to the Sonatype OSS snapshot repository as follows:

% mvn clean deploy -Dbrooklyn.deployTo=sonatype -DskipTests
...

Configure Docker Hub

We also build a Docker image with the Clocker distribution, but the Docker Hub configuration must be updated manually. There is an automated build for clockercentral/clocker and you must be logged into the Hub website with an account that has access to the clockercentral organization. If you do, then you can click on the Build Settings tab, to see the current automated build configuration.

Now, you can edit the current settings. First, replace the existing -SNAPSHOT release with the updated version if appropriate, for the row that configures the master branch. Then, look for the line configuring a tag with the previous version. This can be updated with the tag you created above, for example, v1.2.0, and the version should be set to the current version on the release branch, so simply 1.2.0. Finally, change the line configuring the release branch to use the new branch name if required, in this case release/1.2.x, for the latest image tag. There may be other lines, but they can be ignored.

The settings should look similar to those in the screenshot above, depending on your version numbers. Save these changes using the Save Changes button. This allows Docker Hub to build the Docker images when code is pushed to the GitHub repository.

Push The Changes

The version number changes can now be pushed to GitHub. For the release branch, you will need to push the tag as well:

% git push --force origin release/1.2.x --tags
...

For the master branch, simply push as normal:

% git push origin master

Upload The Artifacts

Make sure you are in the release branch, and check that the distribution archive has been created. This should be in dist/target and there will be two files you need, brooklyn-clocker-dist.tar.gz and the GPG signature named brooklyn-clocker-dist.tar.gz.asc. If you open the releases page of the Clocker GitHub repository, you should see your new tag at the top. Click on this, followed by the Edit Tag button.

You can now update the name of the release to Version X.Y.Z as appropriate, and enter any notes or other information about the release below. In the box below the release information, click on the selecting them text, and you will be presented with a file upload dialog. Find the two release artifacts and select them, and they will be uploaded. Once this is complete, you should click the Publich Release button to save the new release. If the version is a preview or temporary one, it is a good idea to check the This is a pre-release box as well.

Results

• You should see the new versioned release when you view the releases page for Clocker, and will be able to download both the distribution archive and its GPG signature.
• On Docker Hub, or just when running Docker, you should be able to access clockercentral/clocker:X.Y.Z as a new Docker image.
• On the Cloudsoft, and possibly Sonatype, Maven repositories the Jar files for the new release of Clocker will be accessible, and can be found by searching Artifactory or Sonatype Nexus.