This document provides a more detailed explanation of the steps involved in releasing Apache Marmotta and what happens when they are performed.

Prerequisites

Please be also aware of the following documentation on the Apache website:

The whole release process is completely based on Maven and the "Maven Release Plugin", i.e. I added all the necessary steps to a Maven profile that can be used to run the release. Note however that this does not release you from the burden of doing manual checking of the result afterwards!

The release in the following guide is 3.0.0-incubating, so you have to replace that value in all commands with the actual version number!

Check that system builds, carry out some automatic license checking

Start with the latest snapshot build. Make sure your local GIT repository is committed and in sync with the remote repository.

Clean build

Run:

mvn clean install

Do not skip tests. The purpose is to see if the build is working. If it is not, it saves you a lot of trouble doing this easy Maven build. In any later phase you might need to meddle with GIT, clean up repositories, or worse.

RAT Checking

Do:

mvn apache-rat:check

and possibly for creating a html report

mvn apache-rat:rat

This will check if all files have appropriate license headers, except those that have explicitly been included in the parent POM. If a file is excluded in the parent POM, add a comment why this is done, so others can later see the reasons. If the check fails, fix the affected source files, and start over (don't forget to GIT commit and push).

Prepare the Release

The Maven Release Plugin basically has two phases: preparation and the actual release. The prepare phase will

This means that after preparation, both your local working copy and your local repository will already be the new snapshot version! To make it a bit easier to undo such changes, I disabled the automatic GIT push to the upstream GIT repository. Undoing changes in your local repository requires only a bit of GIT meddling. Undoing changes in the remote repository is simply impossible (and dangerous).

In the "prepare" phase, it is possible to do a dry run. Use this last opportunity offered by the system to check if everything is ok:

mvn release:prepare -DreleaseVersion=3.0.0-incubating -DdevelopmentVersion=3.1.0-incubating-SNAPSHOT -DautoVersionSubmodules=true -DdryRun=true

This command will do all the steps of a normal release preparation except running any automatic GIT commands. Can make your live a lot less troublesome in case of errors.

If all goes well, do a "mvn release:clean" and then do the actual preparation:

mvn release:prepare -DreleaseVersion=3.0.0-incubating -DdevelopmentVersion=3.1.0-incubating-SNAPSHOT

Perform the Release

The second step of the Maven Release Plugin is actually performing the release. No dry-run is possible here, so failure is bad. Make sure you have GPG agent running and all passwords configured properly. The phase will carry out the following steps:

mvn release:perform -DconnectionUrl=scm:git:file://`pwd`/.git

The connectionUrl property will redefine the connection url for the GIT repository to the local clone. This reduces the time because the content needs not be retrieved from the remote repository.

The build will be completely clean and simulate the same environment that any user will get who checks out the release tag for the first time on his machine. The three release profiles together have been configured to carry out the following steps:

Already quite cool, but a few manual steps are still remaining to finish the release.

Upload Distribution Assemblies

First of all, check the distribution files in target/checkout/target/3.0.0-incubating, especially regarding license files, readme, and installability.

Distribution files are managed by a dedicated Subversion server. There are two distribution directories in this subversion server that are interesting for Apache Marmotta:

For continuing with the release, please check out both Subversion repositories, e.g. with:

svn co https://dist.apache.org/repos/dist/dev/marmotta/ marmotta-releases-voting
svn co https://dist.apache.org/repos/dist/release/marmotta/ marmotta-releases-final

Now copy over the directory containing the distribution assemblies created by the build process (see above) to the "voting" working copy:

cp -r <MARMOTTA-WORKING-COPY>/target/checkout/target/3.0.0-incubating <VOTING-WORKING-COPY>

add the resulting directory to subversion:

svn add 3.0.0-incubating
svn commit -m "new Apache Marmotta release candidate"

This will upload the release artifacts to the subversion server.

Close Staging Repository

The Maven artifacts are uploaded to a "staging" repository on the ASF Maven Nexus. Staging repositories are separate spaces meant for checking releases before really distributing them. To be able to access this staging repository, it first needs to be closed, so

Closing the repository will carry out some simple consistency and error checks, specifically it will check GPG signatures. You will receive an email once all checks have passed.

While in Nexus, remember the URL of the staging repository by clicking on its name. You will need it later (in my current case this is https://repository.apache.org/content/repositories/orgapachemarmotta-013/)

Push Local GIT to Upstream

Changes have been performed in your local GIT repository, but since we disabled this feature for security reasons, they are not automatically pushed to the upstream repository. So don't forget to do a

git push --tags

Send VOTE E-Mail

The final step in the release process is to send out the VOTE E-Mail to the Marmotta Developer mailinglist. A template for this mail has been prepared for you at

target/checkout/target/vote.txt

This template needs to be completed manually by some information. Particularly, you need to

The voting period is 72 hours. While in incubation, when we have concluded a vote on the developer mailinglist, we also need to run an additional vote on the incubator general mailinglist, so the whole process will be 144 hours (or 6 days).

After the VOTE

VOTE failed: Try again

In case the vote fails, clean up, fix the errors and create a new release candidate (RC)

VOTE passes: Announce the release

If the vote passes, the first thing is to prepare the distribution:

This process usually takes 24 hours. After that the release can be announced :-)

ReleaseProcess (last edited 2014-12-16 09:41:37 by JakobFrank)