[MRELEASE-431] add user documentation for version policies

maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java

@@ -23,7 +23,7 @@
 import org.apache.maven.shared.release.versions.VersionParseException;
 
 /**
- * API for next version calculations, used by maven-release-plugin to suggest release and next develoment versions.
+ * API for next version calculations, used by maven-release-plugin to suggest release and next development versions.
  *
  * @since 2.5.1 (MRELEASE-431)
  */

maven-release-manager/src/main/java/org/apache/maven/shared/release/policies/DefaultVersionPolicy.java

@@ -29,7 +29,8 @@
 import org.apache.maven.shared.release.versions.VersionParseException;
 
 /**
- * <p>DefaultVersionPolicy class.</p>
+ * Default version policy: proposed release version just removes {@code -SNAPSHOT},
+ * next development version adds a minor increment to release and adds {@code -SNAPSHOT}.
  *
  * @author Robert Scholte
  */

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/BranchReleaseMojo.java

@@ -33,8 +33,8 @@
 
 /**
  * Branch a project in SCM, using the same steps as the <code>release:prepare</code> goal, creating a branch instead of
- * a tag. For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/examples/branch.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/branch.html</a>.
+ * a tag. For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/usage/branch.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/branch.html</a>.
  *
  * @author <a href="mailto:[email protected]">Emmanuel Venisse</a>
  * @since 2.0-beta-6

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/CleanReleaseMojo.java

@@ -31,8 +31,8 @@
  * Clean up after a release preparation. This is done automatically after a successful <code>release:perform</code>,
  * so is best served for cleaning up a failed or abandoned release, or a dry run. Note that only the working copy
  * is cleaned up, no previous steps are rolled back.
- * For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/examples/clean-release.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/clean-release.html</a>.
+ * For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/usage/clean-release.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/clean-release.html</a>.
  *
  * @author <a href="mailto:[email protected]">Brett Porter</a>
  */

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java

@@ -38,8 +38,8 @@
 /**
  * Perform a release from SCM, either from a specified tag, or the tag representing the previous release in
  * the working copy created by <code>release:prepare</code>.
- * For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/examples/perform-release.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/perform-release.html</a>.
+ * For more info see <a href="https://maven.apache.org/plugins/maven-release-plugin/usage/perform-release.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/perform-release.html</a>.
  *
  * @author <a href="mailto:[email protected]">Emmanuel Venisse</a>
  * @author <a href="mailto:[email protected]">Brett Porter</a>

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java

@@ -39,8 +39,8 @@
  * Prepare for a release in SCM. Steps through several phases to ensure the POM is ready to be released and then
  * prepares SCM to eventually contain a tagged version of the release and a record in the local copy of the parameters
  * used. This can be followed by a call to <code>release:perform</code>. For more info see <a
- * href="https://maven.apache.org/plugins/maven-release-plugin/examples/prepare-release.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/prepare-release.html</a>.
+ * href="https://maven.apache.org/plugins/maven-release-plugin/usage/prepare-release.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/prepare-release.html</a>.
  *
  * @author <a href="mailto:[email protected]">John Casey</a>
  * @author <a href="mailto:[email protected]">Emmanuel Venisse</a>

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/RollbackReleaseMojo.java

@@ -32,8 +32,8 @@
 /**
  * Rollback changes made by a previous release. This requires that the previous release descriptor
  * <code>release.properties</code> is still available in the local working copy. For more info see <a
- * href="https://maven.apache.org/plugins/maven-release-plugin/examples/rollback-release.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/rollback-release.html</a>.
+ * href="https://maven.apache.org/plugins/maven-release-plugin/usage/rollback-release.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/rollback-release.html</a>.
  *
  * @since 2.0-beta-5
  * @author Edwin Punzalan

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/UpdateVersionsMojo.java

@@ -33,8 +33,8 @@
 /**
  * Update the POM versions for a project. This performs the normal version updates of the <code>release:prepare</code>
  * goal without making other modifications to the SCM such as tagging. For more info see <a
- * href="https://maven.apache.org/plugins/maven-release-plugin/examples/update-versions.html"
- * >https://maven.apache.org/plugins/maven-release-plugin/examples/update-versions.html</a>.
+ * href="https://maven.apache.org/plugins/maven-release-plugin/usage/update-versions.html"
+ * >https://maven.apache.org/plugins/maven-release-plugin/usage/update-versions.html</a>.
  *
  * @author Paul Gier
  * @since 2.0

maven-release-plugin/src/site/apt/index.apt

@@ -53,8 +53,8 @@ Maven Release Plugin
 
 * Usage
 
-  General instructions on how to use the Release Plugin can be found on the {{{./usage.html}usage page}}. Some more
-  specific use cases are described in the examples given below.
+  General instructions on how to use the Release Plugin can be found on the {{{./usage.html}usage page}}, with
+  one additional page per goal. Some more specific use cases are described in the examples given below.
 
   In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
   free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
@@ -74,25 +74,8 @@ Maven Release Plugin
   To provide you with better understanding on some usages of the Maven Release Plugin,
   you can take a look into the following examples:
 
-
-  * {{{./examples/prepare-release.html}Prepare a Release}}
-
-  * {{{./examples/perform-release.html}Perform a Release}}
-
-  * {{{./examples/rollback-release.html}Rollback a Release}}
-
-  * {{{./examples/clean-release.html}Clean a Release}}
-
-  * {{{./examples/generate-release-poms.html}Generate Release POMs}}
-
-  * {{{./examples/lock-files.html}Lock Files During Release}}
-
   * {{{./examples/run-goals-before-commit.html}Run Additional Goals Before Commit}}
 
-  * {{{./examples/branch.html}Create a Branch}}
-
-  * {{{./examples/non-interactive-release.html}Non-interactive Release}}
-
-  * {{{./examples/update-versions.html}Update POM Versions}}
+  * {{{./examples/lock-files.html}Lock Files During Release}}
 
   []

maven-release-plugin/src/site/apt/usage.apt.vm

@@ -72,7 +72,9 @@ Usage
 * Do a Dry Run
 
   Since the Release Plugin performs a number of operations that change the project, it may be wise to do a dry run
-  before a big release or on a new project. To do this, commit all of your files as if you were about to run a full
+  before a big release or on a new project.
+
+  To do this, commit all of your files as if you were about to run a full
   release and run:
 
 ------

maven-release-plugin/src/site/apt/examples/branch.apt → maven-release-plugin/src/site/apt/usage/branch.apt

@@ -25,6 +25,8 @@
 
 Create a Branch
 
+  {{{../branch-mojo.html}<<<release:branch>>> goal}} branches a project in SCM, using the same steps as the {{{./prepare-release.html}<<<release:prepare>>> goal}}, creating a branch instead of a tag.
+
   Creating a branch involves the following release phases {{{../../maven-release-manager/#branch}by default}}:
 
    * Check that there are no uncommitted changes in the sources

maven-release-plugin/src/site/apt/examples/clean-release.apt → maven-release-plugin/src/site/apt/usage/clean-release.apt

@@ -25,6 +25,11 @@
 
 Clean a Release
 
+  {{{../clean-mojo.html}<<<release:clean>>> goal}} cleans up after a release preparation.
+  This is done automatically after a successful <<<release:perform>>>, so is best served for cleaning up a failed or abandoned release, or a dry run.
+
+  Note that only the working copy is cleaned up, no previous steps are rolled back in SCM.
+
   Cleaning a release goes through the following release phases:
 
   * Delete the release descriptor (<<<release.properties>>>)

maven-release-plugin/src/site/apt/examples/perform-release.apt.vm → maven-release-plugin/src/site/apt/usage/perform-release.apt.vm

@@ -27,6 +27,8 @@
 
 Perform a Release
 
+  {{{../perform-mojo.html}<<<release:perform>>> goal}} performs a release from SCM, either from a specified tag, or usually the tag representing the previous release in the working copy created by {{{./prepare-release.html}<<<release:prepare>>>}}.
+
   Performing a release runs the following release phases {{{../../maven-release-manager/#perform}by default}}:
 
    * Checkout from an SCM URL with optional tag to <<<workingDirectory>>> (<<<target/checkout>>> by default)

maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm → maven-release-plugin/src/site/apt/usage/prepare-release.apt.vm

@@ -28,13 +28,16 @@
 
 Prepare a Release
 
+  {{{../prepare-mojo.html}<<<release:prepare>>> goal}} ensures the project is ready to be released and then prepares SCM to eventually contain a tagged version of the release.
+  This is expected to be followed by a call to {{{./perform-release.html}<<<release:perform>>>}}.
+
   Preparing a release goes through the following release phases {{{../../maven-release-manager/#prepare}by default}}:
 
    * Check that there are no uncommitted changes in the sources
 
    * Check that there are no SNAPSHOT dependencies
 
-   * Change the version in the POMs from x-SNAPSHOT to a new version (you will be prompted for the versions to use)
+   * Change the version in the POMs from x-SNAPSHOT to a new release version (you will be prompted for the versions to use, with a default value proposed by version policy configured as <<<projectVersionPolicyId>>>)
 
    * Transform the SCM information in the POM to include the final destination of the tag
 
@@ -44,7 +47,7 @@ Prepare a Release
 
    * Tag the code in the SCM with a version name (this will be prompted for)
 
-   * Bump the version in the POMs to a new value y-SNAPSHOT (these values will also be prompted for)
+   * Bump the version in the POMs to a new value y-SNAPSHOT (these values will also be prompted for, with a default value proposed by version policy configured as <<<projectVersionPolicyId>>>)
 
    * Eventually run completion goal(s) against the project (since 2.2) 
 
@@ -144,3 +147,43 @@ mvn release:prepare-with-pom
     []
 
   The <<<project.>>> prefix is optional and may be omitted.
+
+* Overriding proposed release and next development versions
+
+  The Release Plugin automatically calculates the versions that are proposed for the release and the next development version (i.e. the next SNAPSHOT).
+
+  The default VersionPolicy compares and increments versions for a common java versioning scheme:
+  the proposed release version is the current version without <<<-SNAPSHOT>>>,
+  and the proposed next development version is a minor increment to the release with <<<-SNAPSHOT>>>.
+
+  It is possible to select a different VersionPolicy by specifying its id:
+
++-------------------
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-release-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          <projectVersionPolicyId>SemVerVersionPolicy</projectVersionPolicyId>
+        </configuration>
+      </plugin>
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
++-------------------
+
+  There are 3 VersionPolicies bundled with the Release Plugin:
+
+    * <<<default>>>: increments versions for a common java versioning scheme,
+
+    * <<<OddEvenVersionPolicy>>>: even version numbers for releases, and odd version numbers for development (see {{{../../maven-release-policies/maven-release-oddeven-policy/apidocs/org/apache/maven/shared/release/policy/oddeven/OddEvenVersionPolicy.html}javadoc}}),
+
+    * <<<SemVerVersionPolicy>>>: enforce SemVer format and increase minor element when resolving the development version (see {{{../../maven-release-policies/maven-release-semver-policy/apidocs/org/apache/maven/shared/release/policy/semver/SemVerVersionPolicy.html}javadoc}}).
+
+    []

maven-release-plugin/src/site/site.xml

@@ -43,24 +43,25 @@ under the License.
         <item name="release:update-versions" href="update-versions-mojo.html"/>
         <item name="release:help" href="help-mojo.html"/>
       </item>
-      <item name="Usage" href="usage.html"/>
+      <item name="Usage" href="usage.html" collapse="false">
+        <item name="Non-interactive Release" href="usage/non-interactive-release.html"/>
+        <item name="Prepare a Release" href="usage/prepare-release.html"/>
+        <item name="Perform a Release" href="usage/perform-release.html"/>
+        <item name="Generate Release POMs" href="usage/generate-release-poms.html"/>
+        <item name="Rollback a Release" href="usage/rollback-release.html"/>
+        <item name="Clean a Release" href="usage/clean-release.html"/>
+        <item name="Create a Branch" href="usage/branch.html"/>
+        <item name="Update POM Versions" href="usage/update-versions.html"/>
+      </item>
       <item name="Migrate" href="migrate.html"/>
       <item name="FAQ" href="faq.html"/>
       <!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
       <item name="License" href="http://www.apache.org/licenses/"/>
       <item name="Download" href="../download.html"/>
     </menu>
     <menu name="Examples">
-      <item name="Prepare a Release" href="examples/prepare-release.html"/>
-      <item name="Perform a Release" href="examples/perform-release.html"/>
-      <item name="Rollback a Release" href="examples/rollback-release.html"/>
-      <item name="Clean a Release" href="examples/clean-release.html"/>
-      <item name="Generate Release POMs" href="examples/generate-release-poms.html"/>
-      <item name="Lock Files During Release" href="examples/lock-files.html"/>
       <item name="Run Additional Goals Before Commit" href="examples/run-goals-before-commit.html"/>
-      <item name="Create a Branch" href="examples/branch.html"/>
-      <item name="Non-interactive Release" href="examples/non-interactive-release.html"/>
-      <item name="Update POM Versions" href="examples/update-versions.html"/>
+      <item name="Lock Files During Release" href="examples/lock-files.html"/>
     </menu>
   </body>
 </project>