This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-release.git
The following commit(s) were added to refs/heads/master by this push:
new bf06ef2f [MRELEASE-431] add user documentation for version policies
(#169)
bf06ef2f is described below
commit bf06ef2f5e0fb216ba277168cdb6c485c770db89
Author: Hervé Boutemy <[email protected]>
AuthorDate: Thu Mar 9 08:12:09 2023 +0100
[MRELEASE-431] add user documentation for version policies (#169)
---
.../release/policy/version/VersionPolicy.java | 2 +-
.../release/policies/DefaultVersionPolicy.java | 3 +-
.../maven/plugins/release/BranchReleaseMojo.java | 4 +-
.../maven/plugins/release/CleanReleaseMojo.java | 4 +-
.../maven/plugins/release/PerformReleaseMojo.java | 4 +-
.../maven/plugins/release/PrepareReleaseMojo.java | 4 +-
.../maven/plugins/release/RollbackReleaseMojo.java | 4 +-
.../maven/plugins/release/UpdateVersionsMojo.java | 4 +-
maven-release-plugin/src/site/apt/index.apt | 23 ++---------
maven-release-plugin/src/site/apt/usage.apt.vm | 4 +-
.../src/site/apt/{examples => usage}/branch.apt | 2 +
.../site/apt/{examples => usage}/clean-release.apt | 5 +++
.../{examples => usage}/generate-release-poms.apt | 0
.../non-interactive-release.apt | 0
.../apt/{examples => usage}/perform-release.apt.vm | 2 +
.../apt/{examples => usage}/prepare-release.apt.vm | 47 +++++++++++++++++++++-
.../apt/{examples => usage}/rollback-release.apt | 0
.../apt/{examples => usage}/update-versions.apt | 0
maven-release-plugin/src/site/site.xml | 21 +++++-----
19 files changed, 86 insertions(+), 47 deletions(-)
diff --git
a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
b/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
index e9fd5fce..40c812cc 100644
---
a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
+++
b/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.policy.PolicyException;
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)
*/
diff --git
a/maven-release-manager/src/main/java/org/apache/maven/shared/release/policies/DefaultVersionPolicy.java
b/maven-release-manager/src/main/java/org/apache/maven/shared/release/policies/DefaultVersionPolicy.java
index cf29d386..a3df92a0 100644
---
a/maven-release-manager/src/main/java/org/apache/maven/shared/release/policies/DefaultVersionPolicy.java
+++
b/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.DefaultVersionInfo;
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
*/
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/BranchReleaseMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/BranchReleaseMojo.java
index 7e67b80e..2c18d588 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/BranchReleaseMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/BranchReleaseMojo.java
@@ -33,8 +33,8 @@ import
org.apache.maven.shared.release.config.ReleaseDescriptorBuilder;
/**
* 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
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/CleanReleaseMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/CleanReleaseMojo.java
index 6c2d0097..62eeee52 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/CleanReleaseMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/CleanReleaseMojo.java
@@ -31,8 +31,8 @@ import
org.apache.maven.shared.release.config.ReleaseDescriptorBuilder;
* 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>
*/
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java
index 7994e2a6..c0633222 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java
@@ -38,8 +38,8 @@ import org.codehaus.plexus.util.StringUtils;
/**
* 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>
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java
index a7bc0f12..16b5d24a 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java
@@ -39,8 +39,8 @@ import
org.apache.maven.shared.release.config.ReleaseDescriptorBuilder;
* 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>
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/RollbackReleaseMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/RollbackReleaseMojo.java
index 1f8131e4..5c17de45 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/RollbackReleaseMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/RollbackReleaseMojo.java
@@ -32,8 +32,8 @@ import
org.apache.maven.shared.release.config.ReleaseDescriptorBuilder;
/**
* 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
diff --git
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/UpdateVersionsMojo.java
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/UpdateVersionsMojo.java
index 60f657df..33c93d11 100644
---
a/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/UpdateVersionsMojo.java
+++
b/maven-release-plugin/src/main/java/org/apache/maven/plugins/release/UpdateVersionsMojo.java
@@ -33,8 +33,8 @@ import
org.apache.maven.shared.release.config.ReleaseDescriptorBuilder;
/**
* 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
diff --git a/maven-release-plugin/src/site/apt/index.apt
b/maven-release-plugin/src/site/apt/index.apt
index 25d2de3d..c0b2faf0 100644
--- a/maven-release-plugin/src/site/apt/index.apt
+++ b/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}}
[]
diff --git a/maven-release-plugin/src/site/apt/usage.apt.vm
b/maven-release-plugin/src/site/apt/usage.apt.vm
index 8353bc6c..d0aa9996 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:
------
diff --git a/maven-release-plugin/src/site/apt/examples/branch.apt
b/maven-release-plugin/src/site/apt/usage/branch.apt
similarity index 93%
rename from maven-release-plugin/src/site/apt/examples/branch.apt
rename to maven-release-plugin/src/site/apt/usage/branch.apt
index e255c04f..5881b73b 100644
--- a/maven-release-plugin/src/site/apt/examples/branch.apt
+++ b/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
diff --git a/maven-release-plugin/src/site/apt/examples/clean-release.apt
b/maven-release-plugin/src/site/apt/usage/clean-release.apt
similarity index 77%
rename from maven-release-plugin/src/site/apt/examples/clean-release.apt
rename to maven-release-plugin/src/site/apt/usage/clean-release.apt
index d756db07..5c23b542 100644
--- a/maven-release-plugin/src/site/apt/examples/clean-release.apt
+++ b/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>>>)
diff --git
a/maven-release-plugin/src/site/apt/examples/generate-release-poms.apt
b/maven-release-plugin/src/site/apt/usage/generate-release-poms.apt
similarity index 100%
rename from maven-release-plugin/src/site/apt/examples/generate-release-poms.apt
rename to maven-release-plugin/src/site/apt/usage/generate-release-poms.apt
diff --git
a/maven-release-plugin/src/site/apt/examples/non-interactive-release.apt
b/maven-release-plugin/src/site/apt/usage/non-interactive-release.apt
similarity index 100%
rename from
maven-release-plugin/src/site/apt/examples/non-interactive-release.apt
rename to maven-release-plugin/src/site/apt/usage/non-interactive-release.apt
diff --git a/maven-release-plugin/src/site/apt/examples/perform-release.apt.vm
b/maven-release-plugin/src/site/apt/usage/perform-release.apt.vm
similarity index 92%
rename from maven-release-plugin/src/site/apt/examples/perform-release.apt.vm
rename to maven-release-plugin/src/site/apt/usage/perform-release.apt.vm
index d3dca4b6..2757da16 100644
--- a/maven-release-plugin/src/site/apt/examples/perform-release.apt.vm
+++ b/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)
diff --git a/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
b/maven-release-plugin/src/site/apt/usage/prepare-release.apt.vm
similarity index 67%
rename from maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
rename to maven-release-plugin/src/site/apt/usage/prepare-release.apt.vm
index d7cf6a4a..72368a84 100644
--- a/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm
+++ b/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}}).
+
+ []
diff --git a/maven-release-plugin/src/site/apt/examples/rollback-release.apt
b/maven-release-plugin/src/site/apt/usage/rollback-release.apt
similarity index 100%
rename from maven-release-plugin/src/site/apt/examples/rollback-release.apt
rename to maven-release-plugin/src/site/apt/usage/rollback-release.apt
diff --git a/maven-release-plugin/src/site/apt/examples/update-versions.apt
b/maven-release-plugin/src/site/apt/usage/update-versions.apt
similarity index 100%
rename from maven-release-plugin/src/site/apt/examples/update-versions.apt
rename to maven-release-plugin/src/site/apt/usage/update-versions.apt
diff --git a/maven-release-plugin/src/site/site.xml
b/maven-release-plugin/src/site/site.xml
index 12a8f0ea..53d1649f 100644
--- a/maven-release-plugin/src/site/site.xml
+++ b/maven-release-plugin/src/site/site.xml
@@ -43,7 +43,16 @@ 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 -->
@@ -51,16 +60,8 @@ under the License.
<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>
