Building a Release for Wicket

NB. This is a work in progress, the document is not finished yet!

This document outlines the steps needed to perform a succesful release of Wicket on SourceForge. No intimate knowledge of Wicket or maven is required to perform the release if you use this guide, but should be very handy.

Introduction

The steps will use maven as a build tool, as it helps resolving our dependencies, creating a new website and ultimately upload and perform a SourceForge release for us (not implemented yet).

This document will fall into four parts:

  1. preparing the release
  2. building the release
  3. distributing the release
  4. publicizing the release
The following part of this document describes in detail how to perform each part of building a Wicket release.

Prerequisites

In order to be able to create the news RSS feed, you will need to add the Xalan jar to the MAVEN_HOME/lib/endorsed directory. If you fail to do so, the maven xdoc goal will fail with a JAXP error. You can copy the xalan-2.6.2.jar from your local maven repository (probably located in your home directory in .maven/repository/xalan/jars).

Preparing the Release

This section describes the preparation step to perform a release of the Wicket project.

In short the following steps are performed, each step will be described in more detail in the rest of this section:

  • checkout the latest and greatest from CVS
  • check the issue trackers on SourceForge
  • update the changes.xml document
  • add a news item to the front page and news archive
  • run the unit tests and generate the website locally using maven
  • check the website

Checkout Latest and Greatest

A release normally consists of just one project. However, we use the examples projects as (integration) testcases for Wicket. This makes sense, as the examples are showcases of what can be done with Wicket. As such, they represent normal usecases of the Wicket core components and provide the first feedback on whether the core is still functional.

Normally one will checkout all (Java) projects in CVS. At the moment of writing these projects are:

  • wicket
  • wicket-contrib
  • wicket-quickstart
  • wicket-examples
  • wicket-cdapp-example
  • wicket-hangman-example
Make sure you don't have any outstanding changes in your workspace. If you don't want to release those changes, create a new workspace for building the release, or toss them.

Check Issue Trackers

It is the best when no bugs and support requests are left open.

Also, check which bugs, support request and new features have been solved since the last release, and check if they have been added to the xdocs/changes.xml file. Make sure they are added to the correct release. This file is used by the release process, the Maven changes plugin and the Maven announcement plugin.

Building the Release

This section describes the building stage to perform a release of the Wicket project.

In short the following steps are performed, each step will be described in more detail in the rest of this section:

  • commit all outstanding changes (news items spring to mind)
  • prepare the release using maven
  • create the distributable using maven

Clean Workspace

Make sure all changes in your workspace are commited, or use a new, clean workspace to perform the release.

Prepare the Release Using Maven

Running the tests

First check whether *all* unit tests work. It's no use to perform a release when the unit tests fail. You have to pretty tricky stuff in order to have maven actually build a release when the unittests fail. So just DON'T do it when not all the tests run.

Testing whether all tests run is rather straightforward: 

maven test

When a test fails, maven will output the following: 

BUILD FAILED
File...... c:\maven-1.0\cache\cache\maven-test-plugin-1.6.2\plugin.jelly
Element... fail
Line...... 181
Column.... 54
There were test failures.
Total time: 54 seconds
Finished at: Sun Feb 06 16:48:29 CET 2005

You can find what went wrong in the directory build/test-reports. Just look for the test that failed on the output of the maven test call.

Tagging the Release

It is necessary to tag the release so we can 'go back in time' when something is wrong with code in a released version. This is normally done using a CVS client like Tortoise CVS, but we also use Maven for this, to be more specific, we use the SCM-plugin for this purpose.

The command to do this tagging is: 

maven scm:prepare-release

This command will check whether you have uncommitted changes in your workspace and ask you for the tag and version. The tag is the name of the CVS tag which is used to flag the files in the remote CVS repository. This tag is of the form: WICKET_R_X_Y_Z. Where X denotes the major release number, Y the minor release number, and Z the fix number.

The version is the version number of Wicket which you are going to release. This number is formatted as: X.Y.Z, having X, Y and Z equal to the values in the TAG.

If you are going to release Wicket 1.2.9-beta, then the tag will be: WICKET_R_1_2_9_BETA, and the version 1.2.9-beta. 

TODO TODO TODO TODO TODO

This SCM-plugin performs not only the tagging of the release, but also makes some changes to the following files:

Filename Changes
project.xml sets the <currentVersion> to the released version, adds the released version to the <versions> element.
xdocs/changes.xml sets the date of the release on the corresponding <release> element.

Distributing the Release

This section describes the distribution step to perform a release of the Wicket project. Wicket is downloadable from SourceForge, but also available from the Maven remote repositories. This section describes how to get the Wicket binaries to our users.

In short the following steps are performed, each step will be described in more detail in the rest of this section:

  • upload the distributable to sourceforge
  • upload the generated website using maven
  • create an upload bundle for ibiblio using maven
  • upload the upload bundle to the website
  • create an upload request in JIRA for the maven maintainers

Publicizing the Release

This section describes the publication step after a release of the Wicket project is built. No project can survive without users, and the users need to be informed of the release. Various channels are available to publicize our project on, and this section describes how to do this without much effort.

In short the following steps are performed, each step will be described in more detail in the rest of this section:

  • send announcement text to mailinglists
  • make noise on theserverside.com