Forge Release Management

The Forge is a collection of individual projects, some of which have dependencies on other Forge projects or on the core Terracotta artifacts. When creating release versions of Forge projects it is important to consider these dependencies to ensure that releases are linked against the proper version of their dependencies. This document discusses the process used to create releases and the ordering dependencies among the current set of Forge projects.

Creating a Release

Before creating release version of a project you must first make sure that there exist release versions of all of the projects dependencies, including the parent POM for the project. The section "Forge Project Release Ordering" below specifies the order in which to create releases to ensure that this is the case.

Furthermore, it is a policy of the Terracotta Forge that all releases should be built from a branch rather than from the project trunk. The Forge Philosophy document describes the branching and versioning policies for Forge projects and provides the rationale for using branches to create releases.

To create a release version of a project, use the Maven Release Plugin. Using this plugin helps to enforce proper version management and eases the burden of creating the release. Releasing a project is made in two steps: prepare and perform.

prepare

The prepare step is an interactive session that allows you to resolve any snapshot artifacts into their release version, and to specify information such as the version number to use for the release and the name of the tag to use for the release in Subversion. To begin the prepare step, issue the following command from the project directory:

mvn release:prepare

You will then be prompted for the version number and SCM tag. The version number should be of the form X.X.X and the SCM tag should be of the form release-X.X.X. Note that these values differ from the defaults suggested by Maven.

TODO: provide example release:prepare session

perform

Once the prepare stage is complete it is time to actually perform the release. The perform stage updates version numbers to the values specifed in the prepare stage and creates a tag in Subversion that contains the project in its release-ready state. It also updates the brancy from which the release originates to new development (i.e. snapshot) version numbers. To perform a release, issue the following command from the same directory in which the prepare stage was executed:

mvn release:perform -Dgoals=deploy

Once this step is completed, the automated Forge publication process will recognize the new release and publish the resulting artifacts to the Forge.

Configuration

The release:perform stage will deploy the resulting artifacts into a location where, more likely than not, you wont have an account. Currently this location is the kong server that is available only from within the Terracotta network. You will have to configure your Maven's settings.xml file before you can execute a release:perform:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>kong</id>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>
    <server>
      <id>forge-artifacts</id>
      <username>joedeveloper</username>
      <privateKey>/Users/joedeveloper/.ssh/id_rsa</privateKey>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration>
        <sshExecutable>ssh</sshExecutable>
        <scpExecutable>scp</scpExecutable>
      </configuration>
    </server>
    <server>
      <id>forge-site</id>
      <username>joedeveloper</username>
      <privateKey>/Users/joedeveloper/.ssh/id_rsa</privateKey>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration>
        <sshExecutable>ssh</sshExecutable>
        <scpExecutable>scp</scpExecutable>
      </configuration>
    </server>
  </servers>
</settings>

Forge Project Release Ordering

If more than one Forge project is to be released within the same time frame, they must be released in the following order:

1. skin-parent
2. simple-skin
3. forge-parent
4. application-parent, archetype-parent, plugin-parent, util-parent
5. tc-maven-plugin
6. tim-parent
7. pojo-archetype, tim-archetype, webapp-archetype
8. everything else