content/apt/guides/development/guide-testing-releases.apt

 ------
 Guide to Testing Staged Releases
 ------
 Maven Team
 ------
 2007-12-21
 ------

~~ 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

Guide to Testing Staged Releases

  As part of the release process, the artifacts are staged in a temporary repository
  for testing and evaluation before voting. Such repositories are not available by
  default, so to use them your project must be configured appropriately.
  
  The steps are as follows:

    * add the repository or plugin repository to your POM or settings (see below)

    * ensure you are using the version being released of the artifacts in your project,
      e.g. by setting the <<<\<version\>>>> in the <<<\<plugin\>>>> tag.

    * test the release

    * remove the repository from your POM if it was specified there

    * remove the artifacts from your local repository when you have completed testing

  The repository configuration for testing a plugin will typically look something like this (it will be provided in the vote email):

----
  ...
  <pluginRepositories>
    <pluginRepository>
      <id>staged-releases</id>
      <url>http://people.apache.org/~dfabulich/stage-repo</url>
    </pluginRepository>
  </pluginRepositories>
  ...
----

  The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the 
  release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also
  important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already.

* Setting up Archiva to Test Staged Releases

  These steps will be similar for any repository manager - please refer to their individual documentation for instructions on how to
  configure remote proxies.

  For Archiva, the first step is to create a new managed repository for the staged releases. This will ensure they remain isolated from your 
  environment. On the repositories tab, add a new managed repository with the settings:

    * Identifier = <<<staged-releases>>>

    * Name = Staged Releases

    * Directory = <<</path/to/repositories/staged-releases>>>

    * Uncheck 'Scannable'

  Next add a remote repository with settings similar to the following:

    * Identifier = <<<dfabulich.staged.releases>>>

    * Name = dfabulich Staged Releases

    * URL = <<<http://people.apache.org/~dfabulich/staging-repo/>>>

  Finally, add a proxy connector to connect the two repositories:

    * Managed repository = <<<staged-releases>>>

    * Remote repository = <<<dfabulich.staged>>>

    * Release policy = <<<once>>>

    * Snapshot policy = <<<never>>>

    * White list = <<<org/apache/maven/**>>>

  You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of
  <<<http://localhost:8080/archiva/repository/staged-releases/>>>.

  The advantage of this approach is that you can usually remove your entire local repository afterwards and after removing the staged repository
  from your POM the artifacts will no longer be used. There is no need to remove the repository or artifacts from Archiva itself - unless a
  staged release is updated for further testing.

  It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote
  repository for a different staging repository.

  If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional
  mirror to correspond to the additional repository in the POM, such as:

----
  ...
  <mirror>
    <id>staged-releases-mirror</id>
    <url>http://localhost:8080/archiva/repository/staged-releases/</url>
    <mirrorOf>staged-releases</mirrorOf>
  </mirror>
  ...
----

* Using a Settings Profile

  If you regularly test staged releases and want to have a more convenient way to add the repository to a build without
  modifying your POM, you may add a profile to your POM:

----
  ...
  <profiles>
    <profile>
      <id>staged-releases</id>
      <pluginRepositories>
        <pluginRepository>
          <id>staged-releases</id>
          <url>http://people.apache.org/~dfabulich/stage-repo</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  ...
----

  With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then
  run the build with the following command:

----
mvn verify -Pstaged-releases
----

  Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build
  environment.