 --------------
 Maven SCM Jazz Provider - Working with the Release Plugin
 --------------
 Chris Graham
 --------------
 2012-03-19
 --------------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

 Using the Release Plugin with the Jazz SCM provider.

Maven Releases

  The normal Maven process of creating a release using the Maven Release Plugin
  involves a two step process.
  
  The first step, <<<mvn release:prepare>>> consists of the following phases:

    * check-poms

    * scm-check-modifications
    
    * check-dependency-snapshots
    
    * create-backup-poms
    
    * map-release-versions
    
    * input-variables
    
    * map-development-versions
    
    * rewrite-poms-for-release
    
    * generate-release-poms
    
    * run-preparation-goals
    
    * scm-commit-release
    
    * scm-tag
    
    * rewrite-poms-for-development
    
    * remove-release-poms
    
    * run-completion-goals
    
    * scm-commit-development
    
    * end-release

    []
  
  The tag operation should, as per good SCM practices and Maven best practices,
  create a tag of just that module, and any sub modules in a multi-module project.
  
  The second step, <<<mvn release:perform>>>, consists of the following phases:

    * verify-completed-prepare-phases
    
    * checkout-project-from-scm
    
    * run-perform-goals

    []
    
  The <<<scm create snapshot>>> command, used to implement the Maven SCM Tag command,
  creates an implicit baseline of *ALL* components within the repository workspace.
  For this reason, it is *very strongly* recommended that only a single component
  reside in the repository workspace being used to perform the release.

  A simple suggestion is to use a naming standard of: \<ComponentName\>BuildWorkspace
  for Repository Workspace names used to perform releases.

  Or, put in a Maven context, tagging multiple projects at the same time,
  makes absolutely no sense.

  Now, the question becomes, how do we organise our repository workspaces?
  
Repository Workspace Organisation

  A suggestion of how a developer can work with Maven, multiple components
  and multiple developers is shown below.
     
[images/FlowDiagram.png] Developer Repository Workspaces, Release Repository Workspaces and Streams.

  The important thing to note, is that a developer can have multiple components,
  multiple flow targets. They can quite easily use the usual <<<mvn clean install>>>
  from their Eclipse workspace.
  
  They should not, however, attempt to run the release plugin from these environments.
  
  It is very strongly recommended that a separate repository workspace, containing just one
  component, the component to be released, be set up for exactly this purpose.
  This repository workspace should only have one flow target, which would normally be a stream.
  Should the repository workspace have multiple flow targets, the flow target marked as "current"
  will be the one where the changes are flowed to.
  However, this provider also works perfectly well with a standalone repository workspace, ie,
  no flow targets.

  This means that the <<<scm>>> settings in the pom must to be configured for the build repository
  workspace, not the developer's repository workspace. As the developers should not be performing
  a release, this will not effect them; they will not need to modify the <<<scm>>>
  section in the pom to point to their specific repository workspace.

  This is what the <<<scm>>> section of the pom.xml file could look like:

+--
    <scm>
        <url>https://rtc:9444/jazz:GPDBBuildWorkspace</url>
        <connection>scm:jazz:https://rtc:9444/jazz:GPDBBuildWorkspace</connection>
        <developerConnection>scm:jazz:https://rtc:9444/jazz:GPDBBuildWorkspace</developerConnection>
    </scm>
+--

  As the username and password are not in the pom.xml, they must be obtained from the user's <<<settings.xml>>> file.
  This is a sample of what the <<<server>>> section of the settings.xml file could look like:

+--  
  <servers>

      <server>
        <id>rtc:9444</id>
        <username>build</username>
        <password>build</password>
      </server>

  </servers>
+--

  In this example, we are using the <<<build>>> user. The GPDBBuildWorkspace would be owned by the <<<build>>> user.

Working with Multiple Streams

  The next step in the normal evolution of a software project would be to start development work on the next release or
  version of the software. Let's call it Release 2. Ordinarily, you would create a branch to operate in. In Jazz SCM, we
  create a Stream. 
  
  The image below illustrates how this can be achieved: 
  
[images/FlowDiagramWithMultipleStreams.png] Developer Repository Workspaces, Release Repository Workspaces with Multiple Streams.

  All of the initial repository workspaces flow into the development stream (all implicitly Release 1). When the new
  stream for release 2 has been created, the (Release 1) Development Stream is modified so that it has a flow target
  of the Release 2 Development Stream. The repository workspaces for the Release 2 work are then created and their
  flow targets flow back to the Release 2 Development Stream.
  
  The repository workspaces for the build are again created, and the <<<scm>>> section of the pom.xml file could look like:

+--
    <scm>
        <url>https://rtc:9444/jazz:GPDBBuildR2Workspace</url>
        <connection>scm:jazz:https://rtc:9444/jazz:GPDBBuildR2Workspace</connection>
        <developerConnection>scm:jazz:https://rtc:9444/jazz:GPDBBuildR2Workspace</developerConnection>
    </scm>
+--
   
Working with the Release Plugin
  
  We are able to use the <<<release:prepare>>> and <<<release:perform>>> goals in the one invocation,
  however, due to the sandbox within a sandbox issues discussed, we need to use the <<<workingDirectory>>>
  option.
  
  Here is a sample:
  
+--
mvn -B -Dresume=false -DworkingDirectory=/tmp/maven release:prepare release:perform
+--