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

 -----
 Usage
 -----
 Stephen Connolly
 ------
 2008-09-02
 ------

Usage

  The plugin offers goals for updating the versions of artifacts referenced in
  a Maven <<<pom.xml>>> file.

* Basic Usage

  Maven 2.0, 2.1, 2.2 and 3.0 do not currently support re-reading modifications of the <<<pom.xml>>> within one
  invocation of Maven.

  The following goals:

    * {{{./set-mojo.html}versions:set}}

    * {{{./lock-snapshots-mojo.html}versions:lock-snapshots}}

    * {{{./resolve-ranges-mojo.html}versions:resolve-ranges}}

    * {{{./unlock-snapshots-mojo.html}versions:unlock-snapshots}}

    * {{{./update-child-modules-mojo.html}versions:update-child-modules}}

    * {{{./update-parent-mojo.html}versions:update-parent}}

    * {{{./update-properties-mojo.html}versions:update-properties}}
    
    * {{{./set-property-mojo.html}versions:set-property}}

    * {{{./use-latest-releases-mojo.html}versions:use-latest-releases}}

    * {{{./use-latest-snapshots-mojo.html}versions:use-latest-snapshots}}

    * {{{./use-latest-versions-mojo.html}versions:use-latest-versions}}

    * {{{./use-next-releases-mojo.html}versions:use-next-releases}}

    * {{{./use-next-snapshots-mojo.html}versions:use-next-snapshots}}

    * {{{./use-next-versions-mojo.html}versions:use-next-versions}}

    * {{{./use-releases-mojo.html}versions:use-releases}}

  modify the <<<pom.xml>>> file, you need to run these goals separately from any other goals or life-cycle phases.

  Note: The first time any of the goals that modify the <<<pom.xml>>> file run, they will create a local backup copy
  <<<pom.xml.versionsBackup>>>. Subsequent modifications will leave this backup unchanged.  The
  {{{./accept-mojo.html}versions:commit}} goal will remove the backup copy, while the
  {{{./revert-mojo.html}versions:revert}} goal will restore the backup copy. It is best practice
  to use a Source Code Management system and not rely on the <<<pom.xml.versionsBackup>>> files created by the
  versions-maven-plugin. The {{{./accept-mojo.html}versions:commit}} and {{{./revert-mojo.html}versions:revert}} goals are
  only a "Poor Man's SCM".

* Goals that modify the <<<pom.xml>>>

  Executing any of the following goals may modify your <<<pom.xml>>> file.

** Reverting modifications to the <<<pom.xml>>> files (Note: modifies <<<pom.xml>>> files)

  To restore your <<<pom.xml>>> files to their initial state, before you started modifying it with the
  versions-maven-plugin, invoke the <<<revert>>> goal. Note that it is best practice
  to use a Source Code Management system and not rely on the <<<pom.xml.versionsBackup>>> files created by the
  versions-maven-plugin.

---
mvn versions:revert
---

** Accepting modifications to the <<<pom.xml>>> files

  To accept the modifications made to your <<<pom.xml>>> files by the versions-maven-plugin invoke the <<<commit>>>
  goal. This will have the effect of removing any <<<pom.xml.versionsBackup>>> files. Note that it is best practice
  to use a Source Code Management system and not rely on the <<<pom.xml.versionsBackup>>> files created by the
  versions-maven-plugin.

---
mvn versions:commit
---

** Updating the parent version (Note: modifies <<<pom.xml>>> files)

  To update the parent version of your POM to the latest available, just invoke the <<<update-parent>>> goal.

---
mvn versions:update-parent
---

  {{{./examples/update-parent.html} A more detailed example of the <<<update-parent>>> goal}}.

** Fixing a multi-module build (Note: modifies <<<pom.xml>>> files)

  If you have a multi-module build where the aggregator pom (i.e. the one with packaging of <<<pom>>> and the
  <<<modules>>> section) is also the parent referenced by its child modules, and the aggregator version does not
  match the version specified in the parent section of the child modules, Maven will not let you build the project.
  To fix all the child modules, use the {{{./update-child-modules-mojo.html}versions:update-child-modules}} goal and
  invoke Maven in non-recursive mode.

---
mvn -N versions:update-child-modules
---

  {{{./examples/update-child-modules.html} A more detailed example of the <<<update-child-modules>>> goal}}.

** Updating versions specified by properties (Note: modifies <<<pom.xml>>> files)

  This goal helps when you use properties to define versions.  Please see the
  {{{./examples/update-properties.html}<<<update-properties>>> example}}.

** Updating versions of dependencies (Note: modifies <<<pom.xml>>> files)

  There are a set of goals to help with advancing dependency versions: <<<use-latest-releases>>>, 
  <<<use-latest-snapshots>>>, <<<use-latest-versions>>>, <<<use-next-releases>>>, <<<use-next-snapshots>>>, and
  <<<use-next-versions>>>.

  Please see the {{{./examples/advancing-dependency-versions.html}advancing dependency versions example}}.

** Resolving version ranges (Note: modifies <<<pom.xml>>> files)

  If a pom contains version ranges in one or more dependencies, it can be useful 
  to collapse those ranges to the specific versions used during the build, just invoke the <<<resolve-ranges>>> goal.

---
mvn versions:resolve-ranges
---

  More examples of the {{{./examples/resolve-ranges.html} <<<resolve-ranges>>>}} goal.

** Locking and unlocking -SNAPSHOT versions (Note: modifies <<<pom.xml>>> files)

  If your pom contains a lot of -SNAPSHOT dependencies and those -SNAPSHOT dependencies are a moving target, it
  can sometimes be helpful to temporarily replace the -SNAPSHOT with a locked -YYYYMMDD.HHMMSS-NNN snapshot.
  In the long term, you will need to return to the -SNAPSHOT dependencies and then replace them with their
  release version, but if you need a short term semi-reproducible build, locked -SNAPSHOTs can sometimes be a
  useful hack.

  To replace -SNAPSHOT dependencies with their current locked snapshot equivalents, just invoke the <<<lock-snapshots>>>
  goal.

---
mvn versions:lock-snapshots
---

  More examples of the {{{./examples/lock-snapshots.html} <<<lock-snapshots>>>}} goal.

  To return to regular -SNAPSHOT dependencies, i.e. replace 1.9.6-20090103.152537-3 with 1.9.6-SNAPSHOT, just invoke
  the <<<unlock-snapshots>>> goal.

---
mvn versions:unlock-snapshots
---

  More examples of the {{{./examples/unlock-snapshots.html} <<<unlock-snapshots>>>}} goal.

** Picking up releases of -SNAPSHOT dependencies (Note: modifies <<<pom.xml>>> files)

  It is better to depend on a released version of a dependency, rather than the -SNAPSHOT of that version.  For
  example, it is better to depend on version 1.3.4 rather than 1.3.4-SNAPSHOT.  Of course if you are waiting for
  1.3.4 to be released, you will have had to add 1.3.4-SNAPSHOT as a dependency.

  The <<<use-releases>>> goal will look at your project dependencies and see if any -SNAPSHOT versions have been
  released, replacing the -SNAPSHOT version with the corresponding release version.

  To replace -SNAPSHOT dependencies with their corresponding release version, just invoke the <<<use-releases>>>
  goal.

---
mvn versions:use-releases
---

  More examples of the {{{./examples/use-releases.html} <<<lock-snapshots>>>}} goal.

** Setting the project version

  To set the project version to a specific version, just invoke the <<<set>>> goal.

---
mvn versions:set -DnewVersion=1.0.1-SNAPSHOT
---

  More examples of the {{{./examples/set.html} <<<set>>>}} goal.

* Goals that do not modify the <<<pom.xml>>>

  Executing any of the following goals will not modify your <<<pom.xml>>> file.

** Checking for new versions of plugins

  To get information about newer versions of plugins that you are using in your build, just invoke the
  <<<display-plugin-updates>>> goal.

---
mvn versions:display-plugin-updates
---

  {{{./examples/display-plugin-updates.html} A more detailed example of the <<<display-plugin-updates>>> goal}}.

** Checking for new versions of dependencies

  To get information about newer versions of dependencies that you are using in your build, just invoke the
  <<<display-dependency-updates>>> goal.

---
mvn versions:display-dependency-updates
---

  {{{./examples/display-dependency-updates.html} A more detailed example of the <<<display-dependency-updates>>> goal}}.

** Checking for new versions of specified by properties

  To get information about newer versions of dependencies that you are using in your build, just invoke the
  <<<display-property-updates>>> goal.

---
mvn versions:display-property-updates
---

  {{{./examples/display-property-updates.html} A more detailed example of the <<<display-property-updates>>> goal}}.

* Report Usage

  The plugin also offers some reporting views; these make no changes to your project,
  but makes it easy for reviewers to survey available updates without even having
  to launch Maven themselves. Updates are further categorized as major, minor, and
  incremental, to make it easier to decide which updates to take.

  To add these reports to your project's site, add the following snippet to your POM:

+---+
<reporting>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>versions-maven-plugin</artifactId>
      <version>${pluginVersion}</version>
      <reportSets>
        <reportSet>
          <reports>
            <report>dependency-updates-report</report>
            <report>plugin-updates-report</report>
            <report>property-updates-report</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>
+---+

