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:
Make sure that you use Java 1.4. Usually this means setting JAVA_HOME correctly.
- 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>
Step 2: Releasing POM artifacts
- refer to an already released parent in pom.xml
- mvn -N -Dusername=[svn-user-name] -Dpassword=******** release:prepare
- mvn -N -Dusername=[svn-user-name] -Dpassword=******** release:perform -Darguments="-N -Dgpg.passphrase='[secret_passphrase_here]'" -P release
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!
- 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.
- 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 CocoonThe 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 artifactsIn 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 voteCall 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
Step 7: Publish the artifactsIf the vote passes, the artifacts are copied to public locations:
cp -R /x1/www/people.apache.org/builds/cocoon/ /x1/www/people.apache.org/repo/m2-ibiblio-rsync-repository/
Step 8: Announce the release
Step 9: Update JIRA fieldsCocoon 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)
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
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/