Capra/PreparingForRelease

The general workflow for releases is as follows:

1. Create a local branch for the release that contains all commits that should be part of the release.
2. Create the release using the procedure outlined below.
3. Build the release and publish it using CI.

This document details this process and describes some caveats.

Create a branch for the release

We follow the basic gitflow workflow for development, including releases.

1. Make sure that all commits that should be included in the release are present in the develop branch. If not, please cherry-pick them into develop or rebase develop on the relevant feature branches.
2. Create a release branch from develop using the target release version: git checkout develop; git checkout -b release/0.7.0
3. All fixes for the release should then go into the release branch. Once the release has been performed, this branch can be merged back into master and develop can be rebased on it.

Create the release

Eclipse Capra is using the unleash-maven plugin to prepare for releases. The plugin switches the version numbers to a release version for all pom.xml and metadata files (MANIFEST.MF, feature.xml, etc.), creates a tag for the release and then creates a commit for the switch to the next development version. The tag and this commit are automatically pushed to git. It is worthwhile noting that these changes are immediately pushed to the repository, so that the operation cannot be easily undone.

The tool should be run locally as:

mvn unleash:perform-tycho -Dunleash.developmentVersion=0.7.0-SNAPSHOT -Dunleash.releaseVersion=0.7.0.RC_20190429

The example above shows how to create a Release Candidate. Therefore, the development version is set to the same version as before. Usually, for a full release, we would increment the minor version like this:

mvn unleash:perform-tycho -Dunleash.developmentVersion=0.7.1-SNAPSHOT -Dunleash.releaseVersion=0.7.0

Please note that a release review has to have been completed before a release can be performed.

Known issues:

• Make sure to have ssh-agent running if using git with public/private key. Otherwise, please see the unleash-maven documentation for details on how to provide credentials.
• It is also important to note that Maven version 3.3.9 or higher. Please make sure that this version is installed.
• While pushing the tag works in all cases, it is possible to get a [REJECTED_NONFASTFORWARD] error from Maven if it is not possible to cleanly apply the commit to switch to a new development version. However, this commit remains in the local commit history and can be pushed manually after rebasing. The tag is created in any case.
• Unfortunately, unleash-maven removes some linebreaks in the pom.xml files which means that the copyright comments and the headers do not look pretty. It is not clear how to prevent this yet, so we have to live with that.

Version numbers

In general, we follow the Version_Numbering prescribed by Eclipse. If the version numbering does not follow the prescribed format, an org.eclipse.tycho.versions.engine.IllegalVersionChangeException will be thrown and Maven will stop processing.

Build and publish the release

Once the tag has been created as described above, the build-tag-for-release job can be used to build the update site and publish it to the download area. The build is parameterized with the tag and whether the build is for a milestone or for a release.