Releasing Cocoon

As Cocoon uses Maven 2 as build system, the release process is very simple and only requires a few steps.

Step 1: Prepare your workstation

In order to get started, you have to make sure that your work station is configured correctly:

Java

Make sure that you use Java 1.4. Usually this means setting JAVA_HOME correctly.

GnuPG

Install GnuPG on your workstation and make sure that YOUR key is your default local key. Also add the key to KEYS.

Maven 2

Unix based systems

make sure that you can login to people.apache.org using keys (http://hacks.oreilly.com/pub/h/66)
in the case that your local username is different from your username at people.apache.org, configure it at ~/.m2/settings.xml.
point to an empty local repository

<settings>
  <localRepository>[path to an existing, empty directory</localRepository>
  <servers>
    <server>
      <id>cocoon-staging-repo</id>
      <username>[your username on people.apache.org]</username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>
  </servers>
</settings>

Note: Point to an empty local repository. This ensures that you don't introduce dependencies that can only be fullfilled within your local build environment or after doing the release which puts all created artifacts into your local repository.

Win32 based systems

Fixme: TBD

Step 2: Releasing POM artifacts

refer to an already released parent in pom.xml
mvn -N -Dusername=[svn-user-name] -Dpassword=******** release:prepare -Darguments="-N"
mvn -N -Dusername=[svn-user-name]-Dpassword=******** release:perform -Darguments="-N-Dgpg.passphrase='[secret_passphrase_here]'" -P release

Take care to manually change all poms that have the released pom as a parent. For example you release cocoon-blocks-modules under version 3, before it was 2-SNAPSHOT. The next version increment of that pom is thus 3-SNAPSHOT, and you should manually change all poms that have 2-SNAPSHOT for this parent to 3-SNAPSHOT. Otherwise the trunk build will use "old" ie already released artifacts, which is not desired. The pu.sh script in cocoon/trunk/tools/pom-updater helps to make the update easier.

Step 3: Releasing JAR artifacts

refer to an already released parent in pom.xml
replace all SNAPSHOT dependencies with already deployed artifacts
the dependencies of a POM don't contain version numbers because they are managed by the root POM of Cocoon. By replacing all SNAPSHOT dependencies in the step before, you also have replaced the SNAPSHOT version of the parent with a released version. Make sure that the module that you want to release also works with the versions set in the released root POM! Otherwise you have to override them by setting them manually in the module's POM (sic).
mvn -Dusername=[svn-user-name] -Dpassword=******** release:prepare
mvn -Dusername=[svn-user-name] -Dpassword=******** release:perform -Darguments="-Dgpg.passphrase='[secret_passphrase_here]' -P release,daisy,localDocs,javadocs-script" -P release,daisy,localDocs,javadocs-script

release ... adds all plugins to the build lifecycle which are only necessary at release time (e.g. the GPG plugin)
daisy ... adds the Daisy export plugin to the lifecycle of the site module
javadocs-script ... adds a special report to the report generation phase which adds an apidocs directory to the site output. This directory then contains a script which pulls the Javadocs from a Maven repository and unpacks it.
localDocs ... configures the target directory of the deploy process. This profile has to be configured in the local settings.xml!

if SNAPSHOT dependencies have been replaced before, point again to them
Point all artifacts in trunk to the new snapshot version of this artifact. For this purpose update the dependencies management section of the root pom.

Additional instructions for special modules

Multi-module release of Cocoon Core

Before you can invoke a multi-module release of Cocoon core, go to /trunk/core-modules/pom.xml and enable the dependency management section. This has to contain the complete list of all to be released modules. You have to use the to-be-released version.
Before you can invoke the release procedure from above, run mvn clean install before. This has to be done because of a bug when Maven tries to resolve test-jar dependencies from within the release plugin.
After the release deactivate the dependencyManagement section in /trunk/core-modules/pom.xml again.

Maven plugin

Release the cocoon-rcl-spring-reloader and the cocoon-rcl-webapp-wrapper modules first.
The Maven plugin has two special dependencies that MUSTN'T be declared from within its pom.xml file but are being resolved at runtime. This means that before you run invoke the release procedure, go to the file PrepareWebappMojo.java and set the constants LIB_VERSION_WRAPPER and LIB_VERSION_SPRING_RELOADER to the to-be-released version.
After the release, set the version to the new SNAPSHOT version.

Step 4: Build Cocoon

The next step is testing whether you have set all dependencies on parent or other modules correctly. The best way to do this is pointing to an empty local repository in your ~/.m2/settings.xml file again and do a mvn install -P allblocks from ./cocoon/trunk.

Step 5: Build the Non-Maven release artifacts

In cocoon/trunk/tools/release-builder there is an Ant script that creates release artifacts for blocks, the core, the servlet-service framework and the Cocoon configuration project. Read the instructions at the top of the script and make sure that your system that builds the artifacts is configured properly.

Step 6: Call for a vote

Call for a vote that includes information about

the name and the version of the artifact
the SVN tag (actually we are voting on SCM tags; we have to trust in the release manager that the binaries are generated from the tag)
how to test it
time how long the vote will stay open
pointer to the changes document

Fixme: Add a mail template here

Step 7: Publish the artifacts

If the vote passes, the artifacts are copied to public locations:

Maven repository

Copy the artifacts to the Apache sync repository:

cp -R /x1/www/people.apache.org/builds/cocoon/ /x1/www/people.apache.org/repo/m2-ibiblio-rsync-repository/

If everything worked fine, you you can delete /x1/www/people.apache.org/builds/cocoon/org.

Apache distribution site

Then copy the distribution artifacts (aka Non-Maven release artifacts):

Step 8: Announce the release

Fixme: Add a template here

Step 9: Update JIRA fields

Cocoon has its own JIRA fields of similar meaing to standard fields Affects Version and Fix version but scoped to one component (usually block) only. Administration of these fields can be done only by users having JIRA administration rights (project administration rights are not enough).
As for 3th of Janury, 2008 there are two Cocoon committers with necessary karma:

Grzegorz Kossakowski (gkossakowski (at) apache.org)
Carsten Ziegeler (cziegeler (at) apache.org)

I (Grzegorz) volunteered to take care of administration of these fields whenever need occur. When a new version is being released, write me a short e-mail using following template:

Hi Grzegorz!

I would like you to ask for adjusting values of custom Cocoon project fields in JIRA. Here comes the info about released artifacts:

Aritfact name: cocoon-forms-impl
Version in the POM file *before* preparing the release: 1.0.0-RC2-SNAPSHOT
Version in a released POM: 1.0.0-RC2
Version in the POM file *after* preparing the release: 1.0.0-RC3-SNAPSHOT

This will give me (or any other committer if I'm busy) all necessary information needed for values update.

Tips and tricks

You can probably omit the username and password if you have committed to the cocoon repository before, SVN should have cached your login credentials. (anyway that's how it was for me on Mac OS X)
You can shortcut the execution by specifying both goals in one:
mvn -N release:prepare release:perform ...
Verify a GPG signature: gpg --verify gnupg-x.x.x.tar.gz.sig gnupg-x.x.x.tar.gz
You can reach the staging repository via http at http://people.apache.org/builds/cocoon/

Apache Cocoon