diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index c15997923..000000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,272 +0,0 @@ - ~~ 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 <<>> file. - -* Basic Usage - - Maven 2.0, 2.1, 2.2 and 3.0 do not currently support re-reading modifications of the <<>> 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 <<>> 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 <<>> file run, they will create a local backup copy - <<>>. 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 <<>> 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 <<>> - - Executing any of the following goals may modify your <<>> file. - -** Reverting modifications to the <<>> files (Note: modifies <<>> files) - - To restore your <<>> files to their initial state, before you started modifying it with the - versions-maven-plugin, invoke the <<>> goal. Note that it is best practice - to use a Source Code Management system and not rely on the <<>> files created by the - versions-maven-plugin. - ---- -mvn versions:revert ---- - -** Accepting modifications to the <<>> files - - To accept the modifications made to your <<>> files by the versions-maven-plugin invoke the <<>> - goal. This will have the effect of removing any <<>> files. Note that it is best practice - to use a Source Code Management system and not rely on the <<>> files created by the - versions-maven-plugin. - ---- -mvn versions:commit ---- - -** Updating the parent version (Note: modifies <<>> files) - - To update the parent version of your POM to the latest available, just invoke the <<>> goal. - ---- -mvn versions:update-parent ---- - - {{{./examples/update-parent.html} A more detailed example of the <<>> goal}}. - -** Fixing a multi-module build (Note: modifies <<>> files) - - If you have a multi-module build where the aggregator pom (i.e. the one with packaging of <<>> and the - <<>> 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 <<>> goal}}. - -** Updating versions specified by properties (Note: modifies <<>> files) - - This goal helps when you use properties to define versions. Please see the - {{{./examples/update-properties.html}<<>> example}}. - -** Updating versions of dependencies (Note: modifies <<>> files) - - There are a set of goals to help with advancing dependency versions: <<>>, - <<>>, <<>>, <<>>, <<>>, and - <<>>. - - Please see the {{{./examples/advancing-dependency-versions.html}advancing dependency versions example}}. - -** Resolving version ranges (Note: modifies <<>> 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 <<>> goal. - ---- -mvn versions:resolve-ranges ---- - - More examples of the {{{./examples/resolve-ranges.html} <<>>}} goal. - -** Locking and unlocking -SNAPSHOT versions (Note: modifies <<>> 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 <<>> - goal. - ---- -mvn versions:lock-snapshots ---- - - More examples of the {{{./examples/lock-snapshots.html} <<>>}} goal. - - To return to regular -SNAPSHOT dependencies, i.e. replace 1.9.6-20090103.152537-3 with 1.9.6-SNAPSHOT, just invoke - the <<>> goal. - ---- -mvn versions:unlock-snapshots ---- - - More examples of the {{{./examples/unlock-snapshots.html} <<>>}} goal. - -** Picking up releases of -SNAPSHOT dependencies (Note: modifies <<>> 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 <<>> 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 <<>> - goal. - ---- -mvn versions:use-releases ---- - - More examples of the {{{./examples/use-releases.html} <<>>}} goal. - -** Setting the project version - - To set the project version to a specific version, just invoke the <<>> goal. - ---- -mvn versions:set -DnewVersion=1.0.1-SNAPSHOT ---- - - More examples of the {{{./examples/set.html} <<>>}} goal. - -* Goals that do not modify the <<>> - - Executing any of the following goals will not modify your <<>> 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 - <<>> goal. - ---- -mvn versions:display-plugin-updates ---- - - {{{./examples/display-plugin-updates.html} A more detailed example of the <<>> 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 - <<>> goal. - ---- -mvn versions:display-dependency-updates ---- - - {{{./examples/display-dependency-updates.html} A more detailed example of the <<>> 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 - <<>> goal. - ---- -mvn versions:display-property-updates ---- - - {{{./examples/display-property-updates.html} A more detailed example of the <<>> 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: - -+---+ - - - - org.codehaus.mojo - versions-maven-plugin - ${pluginVersion} - - - - dependency-updates-report - plugin-updates-report - property-updates-report - - - - - - -+---+ - diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm new file mode 100644 index 000000000..dafa24520 --- /dev/null +++ b/src/site/markdown/usage.md.vm @@ -0,0 +1,258 @@ +title: Usage +autor: Stephen Connolly +date: 2008-09-02 + + + +## Velocity uses # as a prefix for macros and ## as a prefix for comments +#set($h1 = '#') +#set($h2 = '##') +#set($h3 = '###') + +$h1 Usage + +The plugin offers goals for updating the versions of artifacts referenced in +a Maven `pom.xml` file. + +$h2 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: +- [versions:set](./set-mojo.html) +- [versions:lock-snapshots](./lock-snapshots-mojo.html) +- [versions:resolve-ranges](./resolve-ranges-mojo.html) +- [versions:unlock-snapshots](./unlock-snapshots-mojo.html) +- [versions:update-child-modules](./update-child-modules-mojo.html) +- [versions:update-parent](./update-parent-mojo.html) +- [versions:update-properties](./update-properties-mojo.html) +- [versions:set-property](./set-property-mojo.html) +- [versions:use-latest-releases](./use-latest-releases-mojo.html) +- [versions:use-latest-snapshots](./use-latest-snapshots-mojo.html) +- [versions:use-latest-versions](./use-latest-versions-mojo.html) +- [versions:use-next-releases](./use-next-releases-mojo.html) +- [versions:use-next-snapshots](./use-next-snapshots-mojo.html) +- [versions:use-next-versions](./use-next-versions-mojo.html) +- [versions:use-releases](./use-releases-mojo.html) + +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 +[versions:commit](./commit-mojo.html) goal will remove the backup copy, while the +[versions:revert](./revert-mojo.html) 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 [versions:commit](./commit-mojo.html) and [versions:revert](./revert-mojo.html) goals are +only a "Poor Man's SCM". + +$h2 Goals that modify the `pom.xml` + +Executing any of the following goals may modify your `pom.xml` file. + +$h3 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. + +```sh +mvn versions:revert +``` + +$h3 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. + +```sh +mvn versions:commit +``` + +$h3 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. + +```sh +mvn versions:update-parent +``` + +[A more detailed example of the `update-parent` goal](./examples/update-parent.html). + +$h3 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 [versions:update-child-modules](./update-child-modules-mojo.html) goal and +invoke Maven in non-recursive mode. + +``` +mvn -N versions:update-child-modules +``` + +[A more detailed example of the `update-child-modules` goal](./examples/update-child-modules.html). + +$h3 Updating versions specified by properties (Note: modifies `pom.xml` files) + +This goal helps when you use properties to define versions. Please see the +[`update-properties` example](./examples/update-properties.html). + +$h3 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 [advancing dependency versions example](./examples/advancing-dependency-versions.html). + +$h3 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. + +```sh +mvn versions:resolve-ranges +``` + +More examples of the [`resolve-ranges`](./examples/resolve-ranges.html) goal. + +$h3 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. + +```sh +mvn versions:lock-snapshots +``` + +More examples of the [`lock-snapshots`](./examples/lock-snapshots.html) 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. + +```sh +mvn versions:unlock-snapshots +``` + +More examples of the [`unlock-snapshots`](./examples/unlock-snapshots.html) goal. + +$h3 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. + +```sh +mvn versions:use-releases +``` + +More examples of the [`lock-snapshots`](./examples/use-releases.html) goal. + +$h3 Setting the project version + +To set the project version to a specific version, just invoke the `set` goal. + +```sh +mvn versions:set -DnewVersion=1.0.1-SNAPSHOT +``` + +More examples of the [`set`](./examples/set.html) goal. + +$h2 Goals that do not modify the `pom.xml` + +Executing any of the following goals will not modify your `pom.xml` file. + +$h3 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. + +```sh +mvn versions:display-plugin-updates +``` + +[A more detailed example of the `display-plugin-updates` goal](./examples/display-plugin-updates.html). + +$h3 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. + +```sh +mvn versions:display-dependency-updates +``` + +[A more detailed example of the `display-dependency-updates` goal](./examples/display-dependency-updates.html). + +$h3 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. + +```sh +mvn versions:display-property-updates +``` + +[A more detailed example of the `display-property-updates` goal](./examples/display-property-updates.html). + +$h2 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: + +```xml + + + + org.codehaus.mojo + versions-maven-plugin + ${pluginVersion} + + + + dependency-updates-report + plugin-updates-report + property-updates-report + + + + + + +``` +