From 717bd0d9e7027e06a17cedbaa1ae7bec4730f8e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= Date: Sun, 5 Mar 2023 18:38:47 +0100 Subject: [PATCH 1/4] [MRELEASE-431] add user documentation for version policies --- .../release/policy/version/VersionPolicy.java | 2 +- .../policies/DefaultVersionPolicy.java | 3 ++- .../site/apt/examples/prepare-release.apt.vm | 19 +++++++++++++++++-- 3 files changed, 20 insertions(+), 4 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 e9fd5fce2..40c812cc0 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.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 cf29d3868..a3df92a0b 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.VersionParseException; /** - *

DefaultVersionPolicy class.

+ * 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/site/apt/examples/prepare-release.apt.vm b/maven-release-plugin/src/site/apt/examples/prepare-release.apt.vm index d7cf6a4a5..f102e0c3c 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 @@ -34,7 +34,7 @@ Prepare a Release * 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 <<>>) * Transform the SCM information in the POM to include the final destination of the tag @@ -44,7 +44,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 <<>>) * Eventually run completion goal(s) against the project (since 2.2) @@ -144,3 +144,18 @@ mvn release:prepare-with-pom [] The <<>> prefix is optional and may be omitted. + +* Overriding the release and next development versions proposed by default + + 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 proposed values policy can be configured by {{{/prepare-mojo.html#projectVersionPolicyId}<<>> parameter}}. + + Maven Release Plugin provides 2 alternate policies: + + * <<>>: 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}}), + + * <<>>: 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}}). + + [] From af8977083478f92890a8685ff7a7afe56c215f49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= Date: Tue, 7 Mar 2023 02:48:11 +0100 Subject: [PATCH 2/4] move examples to usage --- maven-release-plugin/src/site/site.xml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/maven-release-plugin/src/site/site.xml b/maven-release-plugin/src/site/site.xml index 12a8f0ea3..66467db85 100644 --- a/maven-release-plugin/src/site/site.xml +++ b/maven-release-plugin/src/site/site.xml @@ -43,7 +43,17 @@ under the License. - + + + + + + + + + + + @@ -51,16 +61,7 @@ under the License. - - - - - - - - - From d26d39fe37721f0d37477c9ffa295feb5f73e781 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= Date: Tue, 7 Mar 2023 02:58:12 +0100 Subject: [PATCH 3/4] 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 <<>> 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}<<>> 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: + ++------------------- + + ... + + + + org.apache.maven.plugins + maven-release-plugin + ${project.version} + + SemVerVersionPolicy + + + + ... + + ... + ++------------------- + + There are 3 VersionPolicies bundled with the Release Plugin: + + * <<>>: increments versions for a common java versioning scheme, * <<>>: 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}}), - * <<>>: 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}}). + * <<>>: 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: ------ From c7dcc945a35275354f7b635980243fd32c1a4ca3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= Date: Wed, 8 Mar 2023 01:57:21 +0100 Subject: [PATCH 4/4] tidy up --- .../plugins/release/BranchReleaseMojo.java | 4 ++-- .../plugins/release/CleanReleaseMojo.java | 4 ++-- .../plugins/release/PerformReleaseMojo.java | 4 ++-- .../plugins/release/PrepareReleaseMojo.java | 4 ++-- .../plugins/release/RollbackReleaseMojo.java | 4 ++-- .../plugins/release/UpdateVersionsMojo.java | 4 ++-- maven-release-plugin/src/site/apt/index.apt | 23 +++---------------- .../site/apt/{examples => usage}/branch.apt | 2 ++ .../apt/{examples => usage}/clean-release.apt | 5 ++++ .../generate-release-poms.apt | 0 .../non-interactive-release.apt | 0 .../perform-release.apt.vm | 2 ++ .../prepare-release.apt.vm | 3 +++ .../{examples => usage}/rollback-release.apt | 0 .../{examples => usage}/update-versions.apt | 0 maven-release-plugin/src/site/site.xml | 18 +++++++-------- 16 files changed, 36 insertions(+), 41 deletions(-) rename maven-release-plugin/src/site/apt/{examples => usage}/branch.apt (93%) rename maven-release-plugin/src/site/apt/{examples => usage}/clean-release.apt (77%) rename maven-release-plugin/src/site/apt/{examples => usage}/generate-release-poms.apt (100%) rename maven-release-plugin/src/site/apt/{examples => usage}/non-interactive-release.apt (100%) rename maven-release-plugin/src/site/apt/{examples => usage}/perform-release.apt.vm (92%) rename maven-release-plugin/src/site/apt/{examples => usage}/prepare-release.apt.vm (96%) rename maven-release-plugin/src/site/apt/{examples => usage}/rollback-release.apt (100%) rename maven-release-plugin/src/site/apt/{examples => usage}/update-versions.apt (100%) 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 7e67b80eb..2c18d588f 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 @@ /** * Branch a project in SCM, using the same steps as the release:prepare goal, creating a branch instead of - * a tag. For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/branch.html. + * a tag. For more info see https://maven.apache.org/plugins/maven-release-plugin/usage/branch.html. * * @author Emmanuel Venisse * @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 6c2d00974..62eeee526 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 @@ * Clean 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. - * For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/clean-release.html. + * For more info see https://maven.apache.org/plugins/maven-release-plugin/usage/clean-release.html. * * @author Brett Porter */ 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 7994e2a65..c06332223 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 @@ /** * Perform a release from SCM, either from a specified tag, or the tag representing the previous release in * the working copy created by release:prepare. - * For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/perform-release.html. + * For more info see https://maven.apache.org/plugins/maven-release-plugin/usage/perform-release.html. * * @author Emmanuel Venisse * @author Brett Porter 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 a7bc0f126..16b5d24aa 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 @@ * 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 release:perform. For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/prepare-release.html. + * 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. * * @author John Casey * @author Emmanuel Venisse 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 1f8131e47..5c17de459 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 @@ /** * Rollback changes made by a previous release. This requires that the previous release descriptor * release.properties is still available in the local working copy. For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/rollback-release.html. + * 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. * * @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 60f657dfd..33c93d114 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 @@ /** * Update the POM versions for a project. This performs the normal version updates of the release:prepare * goal without making other modifications to the SCM such as tagging. For more info see https://maven.apache.org/plugins/maven-release-plugin/examples/update-versions.html. + * 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. * * @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 25d2de3d9..c0b2faf06 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/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 e255c04f7..5881b73b0 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}<<>> goal}} branches a project in SCM, using the same steps as the {{{./prepare-release.html}<<>> 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 d756db07e..5c23b542a 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}<<>> goal}} cleans up after a release preparation. + This is done automatically after a successful <<>>, 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 (<<>>) 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 d3dca4b6e..2757da162 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}<<>> 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}<<>>}}. + Performing a release runs the following release phases {{{../../maven-release-manager/#perform}by default}}: * Checkout from an SCM URL with optional tag to <<>> (<<>> 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 96% 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 4c3b12204..72368a840 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,6 +28,9 @@ Prepare a Release + {{{../prepare-mojo.html}<<>> 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}<<>>}}. + 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 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 66467db85..53d1649fb 100644 --- a/maven-release-plugin/src/site/site.xml +++ b/maven-release-plugin/src/site/site.xml @@ -44,15 +44,14 @@ under the License. - - - - - - - - - + + + + + + + + @@ -61,6 +60,7 @@ under the License. +