Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
The general workflow for releases is as follows:
- Create a local branch for the release that contains all commits that should be part of the release.
- Create the release using the procedure outlined below.
- 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.
- 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
developor rebase develop on the relevant feature branches.
- Create a release branch from
developusing the target release version:
git checkout develop; git checkout -b release/0.7.0
- 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.
Note: For the release to be successful, remote tracking needs to be enabled for the branch created in this step, e.g., by using:
git push --set-upstream origin release/0.7.0. For details, please see here.
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 (
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.
- Make sure to have
ssh-agentrunning if using git with public/private key. Otherwise, please see the unleash-maven documentation for details on how to provide credentials. On macos, you will also need to make sure that the
ssh-agentis aware of your keys as described here. If Maven fails to authenticate itself to the Git repository, this might be due to the need to enter the passphrase for the private key. In this case, opening a new shell with
ssh-agent bashfollowed by
ssh-addas described here can help.
- 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.
unleash-mavenremoves some linebreaks in the
pom.xmlfiles 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.
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.
The final step is to rebase
master on the current
develop branch. If a specific release branch was used, that should also be pushed and merged with