From d26d39fe37721f0d37477c9ffa295feb5f73e781 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= <hboutemy@apache.org>
Date: Tue, 7 Mar 2023 02:58:12 +0100
Subject: [PATCH] merge documentation written in #104

---
 .../site/apt/examples/prepare-release.apt.vm  | 37 ++++++++++++++++---
 .../src/site/apt/usage.apt.vm                 |  4 +-
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm b/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
index f102e0c3c..4c3b12204 100644
--- a/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
+++ b/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
@@ -145,17 +145,42 @@ mvn release:prepare-with-pom
 
   The <<<project.>>> prefix is optional and may be omitted.
 
-* Overriding the release and next development versions proposed by default
+* Overriding proposed release and next development versions
 
-  By default, 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>>>.
+  The Release Plugin automatically calculates the versions that are proposed for the release and the next development version (i.e. the next SNAPSHOT).
 
-  The proposed values policy can be configured by {{{/prepare-mojo.html#projectVersionPolicyId}<<<projectVersionPolicyId>>> parameter}}.
+  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>>>.
 
-  Maven Release Plugin provides 2 alternate policies:
+  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>>>: 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}}).
+    * <<<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}}).
 
     []
diff --git a/maven-release-plugin/src/site/apt/usage.apt.vm b/maven-release-plugin/src/site/apt/usage.apt.vm
index 8353bc6ce..d0aa99963 100644
--- a/maven-release-plugin/src/site/apt/usage.apt.vm
+++ b/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:
 
 ------