[CONF] Apache Felix: Release Management (page edited)

confluence Sun, 05 Apr 2009 02:00:35 -0700

Page Edited : FELIX : Release Management

Release Management has been edited by Marcel Offermans (Apr 05, 2009).

Change summary:

Incorporated Clement's suggestions on the mailing list.

(View changes)

Content:

This is a draft for a how to about releasing artifacts from Apache Felix:

Most of the work is done by Maven.

Prerequisites

To prepare or perform a release you MUST BE at least a Apache Felix Committer

Each and every release must be signed; therefore the public key should be cross signed by other Apache committers (not required but suggested).
The public key should be added to http://www.apache.org/dist/felix/KEYS (See Appendix A)

When preparing the release on Mac OS X, check out Appendix F before trying the steps in the next chapter.

Building the Release Candidates

Make sure that an appropriate version for the release is entered in Jira

Build the release artifacts with Maven (the following instructions work on Unix systems, for Windows use a different path than /tmp)

mvn -Prelease -Darguments="-Prelease -DaltDeploymentRepository=local::default::file:///tmp" -DaltDeploymentRepository=local::default::file:///tmp  release:prepare

mvn -Prelease -Darguments="-Prelease -DaltDeploymentRepository=local::default::file:///tmp" -DaltDeploymentRepository=local::default::file:///tmp  release:perform

The above commands created a tag in svn, deployed the release candidates into your /tmp directory, signed the binaries and created the md5/sha1 files.
Beautify the checksums (see Appendix B)
Upload these files to people.apache.org into your home folder and put them there together with the KEYS file containing your public key so we can verify the signatures.
Start the vote thread, wait 72 hours.
If the vote fails (easy case first) remove the tag from svn - done
If the vote is successful, publish the release (see below)
Create a new version for the artifact in jira.

Publishing the Release

If the vote is successful:

copy the released artifacts to the dist directory on www.apache.org/dist/felix
delete the old release there (its archived)
deploy the release to the maven repository
Update the news section on the website
Update the download page on the website to point to the new release.
If you're releasing bundles, you can add it to the Felix Release OBR (see below the Appendix E).

For the last two tasks, it's better to give the mirrors some time to distribute the uploaded artifacts (one day should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts.

Appendix A: Create and Add your key to http://www.apache.org/dist/felix/KEYS

Considering that you are using a *nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following command:

Create a public/private pair key:
```
gpg --gen-key
```
When gpg asks for e-mail linked the key you MUST USE the <committer>@apache.org one
When gpg asks for comment linked the key you SHOULD USE "CODE SIGNING KEY"

Add the key to http://www.apache.org/dist/felix/KEYS: type the following command replacing the word e-mail with your Apache's one (<committer>@apache.org).

(gpg --list-sigs e-mail && gpg --export --armor e-mail) > toadd.key
scp toadd.key people.apache.org:
ssh people.apache.org "cat toadd.key >> /x1/www/www.apache.org/dist/felix/KEYS"

You are DONE, but to see the changes on http://www.apache.org/dist/felix/KEYS you must wait 2 hours

Appendix B: Beautifying the checksums

The checksum files generated by Maven are not directly usable with all tools. So the following scripts beautify these:

for f in *.md5 ; do g=`echo $f | sed "s/\.md5//"` ; echo "  $g" >> $f ;
done
   for f in *.sha1 ; do g=`echo $f | sed "s/\.sha1//"` ; echo "  $g" >> $f ;
done

Appendix C: Script to check releases

Felix Meschberger has developed a set of script aim at testing the file to release. You can find them here:
http://people.apache.org/~fmeschbe/release_helpers/

For those, using the Felix's script to create their releases, the last maven-release-plugin has changed. So, it doesn't work anymore. You have to add the

-DmavenExecutorId=forked-path

property to have the former behavior. If not, you won't be able to enter your GPG passphrase.

I'm sure there is others turn around, but at least this one works.

So, for mac users, it is something like:

mvn -Prelease -Darguments="-Prelease ${REPO}" ${REPO} -DmavenExecutorId=forked-path release:prepare -Dusername=clement -Dpassword=*********
svn up -r head
mvn release:prepare -Dresume
mvn -Prelease -Darguments="-Prelease ${REPO}" ${REPO} -DmavenExecutorId=forked-path release:perform

Appendix D: Control the release process manually

The release process is a two-step process. First the release is prepared and the release candidates are performed.
However, for some dark reasons (☺), you would like to manage the preparation process with more control. Then, you can to the creation of the RC with maven. However, the explained process follows exactly what maven does.

Preparation steps

Check that there's no uncommitted changes in the sources
Check that there's no SNAPSHOT dependencies
-> Both for plugins and dependencies
-> Change the version in the poms from x-SNAPSHOT to a new version
Compile your artifact from scratch
```
mvn clean install
```
Update your pom file to add SCM information:
-> The TAG_NAME must be under the form $ARTIFACT_ID-$VERSION

Add the following element at the end of your pom file (before </project>:

<scm> 
<connection>scm:svn:https://svn.apache.org/repos/asf/felix/releases/YOUR_TAG</connection>
<developerConnection>scm:svn:https://svn.apache.org/repos/asf/felix/releases/YOUR_TAG</developerConnection>
<url>scm:svn:https://svn.apache.org/repos/asf/felix/releases/YOUR_TAG</url>
</scm>

Try to create assemblies and to sign them (dry run)
```
mvn verify -Prelease
```
-> This command creates assemblies and sign them according to the 'release' profile set in the Felix global pom file.
You can also test your project to check that everything works as expected
-> Test your project
-> Check that RC files contains the correct LICENSE and NOTICE
-> Run arat to check missing header file
-> Check that the changelog.txt file are available in the doc folder
-> ...
Commit the changes
-> Commit message is generally something like:
```
prepare release YOUR_TAG
```
Creates the tag
-> The tag must be creates in https://svn.apache.org/repos/asf/felix/releases/TAG_NAME
-> The TAG_NAME must be under the form: $ARTIFACT_ID-$VERSION

Perform the release candidates

You must create the release candidates from the created tags. You can do it by executing the following command:

mvn -Prelease -Dtag=TAG_NAME -DtagBase=https://svn.apache.org/repos/asf/felix/releases -DconnectionUrl=scm:svn:https://svn.apache.org/repos/asf/felix/releases/ -Darguments="-Prelease -DaltDeploymentRepository=local::default::file:///tmp" -DaltDeploymentRepository=local::default::file:///tmp release:perform

Update the 'altDeploymentRepository' path (twice) to fit with your configuration (this works on Linux and MacOS X)
The perform phase does the following actions:

Checkout the tagged version
Compile it
Create assemblies (project and bin)
Sign artifacts (assemblies)
Copy those artifacts in the 'altDeploymentRepository'

Don't forget to beautify .md5 and .sha1 files and check signatures of the generated files. Then you can upload those files on people.apache.org and call the vote...

Prepare to the next development iteration

Go back to your working copy of the trunk code. Edit the pom files to update the version number to the next development iteration version (don't forget the -SNAPSHOT).
Then remove the <scm></scm> element added at the end of your pom file.
Commit the resulting file. Commit message is generally something like:

Prepares for next development iteration (NEW_VERSION)

That's all. Now you can control more finely how to prepare your release and demystify the maven-release-plugin.

Appendix E: Deploy bundles on the Felix OBR

If you're releasing bundles, you can add it to the Felix Release OBR. To do this, you execute the following command:

mvn clean install \
    org.apache.felix:maven-bundle-plugin:deploy \
    -DprefixUrl=http://repo1.maven.org/maven2 \
    -DremoteOBR=releases.xml \
    -DaltDeploymentRepository=apache.releases::default::scp://people.apache.org/www/felix.apache.org/obr

The http://felix.apache.org/obr/releases.xml page is updated during the web site synchronization.
Note: the project building the bundle must use the maven-bundle-plugin and use a version superior or equals to 1.4.2.

Appendix F: Releasing on Mac OS X

When running the mvn release:prepare command, you might get the following error:

[INFO] Executing: svn --non-interactive commit --file /tmp/maven-scm-802409492.commit --targets /tmp/maven-scm-18804-targets
[INFO] Working directory: /homedir/dev/felix/dependencymanager
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Unable to commit files
Provider message:
The svn command failed.
Command output:
svn: Commit failed (details follow):
svn: MKACTIVITY of '/repos/asf/!svn/act/4f11ad5d-9161-0410-b4dd-cb727141ea8c': authorization failed (https://svn.apache.org)

There is a bug in svn on the Mac, as described by Brett Porter in his blog. He proposes to put a "svn" script at the head of your path to fix the issue. That solved the issue for me so I'm mentioning it here to save people the lookup.

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences