[maven-release] branch master updated: [MRELEASE-955] add upgrade from 2 to 3 impact on release profiles

[hb...@apache.org]

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 fae7201e [MRELEASE-955] add upgrade from 2 to 3 impact on release profiles
fae7201e is described below

commit fae7201e1670176eff3402a72d4ae7a7b5802e8c
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sun Apr 24 03:02:12 2022 +0200

    [MRELEASE-955] add upgrade from 2 to 3 impact on release profiles
---
 maven-release-plugin/src/site/apt/upgrade.apt.vm | 98 ++++++++++++++++++++++++
 maven-release-plugin/src/site/site.xml           |  1 +
 2 files changed, 99 insertions(+)

diff --git a/maven-release-plugin/src/site/apt/upgrade.apt.vm b/maven-release-plugin/src/site/apt/upgrade.apt.vm
new file mode 100644
index 00000000..93f66930
--- /dev/null
+++ b/maven-release-plugin/src/site/apt/upgrade.apt.vm
@@ -0,0 +1,98 @@
+  ------
+  Upgrading Maven Release Plugin From 2 to 3
+  ------
+  ------
+  2022-04-24
+  ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Upgrading Maven Release Plugin From 2 to 3
+
+* Context: Maven 3 and Maven 4
+
+  Maven 3 (and previously 2) provides a default release profile named <<<release-profile>>> that builds and attaches source and javadoc jar:
+  this is defined in {{{/ref/3.8.5/maven-model-builder/super-pom.html}the super POM}}. This profile is activated by default during <<<release:perform>>>
+  with Maven Release Plugin 2.x, unless deactivated by configuring <<<useReleaseProfile>>> parameter to <<<false>>>.
+
+  In Maven 4, this default profile will be removed from super POM (see {{{https://issues.apache.org/jira/browse/MNG-7029}MNG-7029}}).
+
+  To prepare for this removal, Maven Release Plugin 3.0 stopped invoking this profile by default: <<<useReleaseProfile>>> parameter is <<<false>>> by default.
+
+* Upgrading Maven Release Plugin 2 to 3
+
+** Write And Configure Your Own Release Profile 
+
+  In order to prepare for Maven 4, each project will instead require to define their own release profile that they'll be able to customise
+  to match their needs:
+
+  * for internal projects, just configure the <<<maven-source-plugin>>> for example
+
+  * for projects published to Maven Central repository, you'll need to add also <<<maven-javadoc-plugin>>> and <<<maven-gpg-plugin>>>: see
+    {{{https://central.sonatype.org/publish/publish-maven/}the documentation}}
+
+   []
+
+  Then configure <<<maven-release-plugin>>> to use that profile during <<<release:perform>>> with <<<releaseProfiles>>> parameter:
+
++-------+
+<project>
+  [...]
+  <build>
+    [...]
+    <plugins>
+      [...]
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-release-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          <releaseProfiles>my-project-release</releaseProfiles>
+        </configuration>
+      </plugin>
+      [...]
+    </plugins>
+    [...]
+  </build>
+
+  [...]
+
+  <profiles>
+    <profile>
+      <id>my-project-release</id>
+      <build>
+        <plugins>
+         [...
+          put here your release-specific plugins invocations, like maven-source-plugin, maven-javadoc-plugin, maven-gpg-plugin, ...
+          ...]
+        </plugins>
+      </build>
+    </profile>
+    [...]
+  </profiles>
+</project>
++-------+
+ 
+** Short Term: Force Using Maven 3-only Default Release Profile
+
+  Configuring explicitely <<<useReleaseProfile>>> parameter to <<<true>>> will force Maven Release Plugin 3 to work like version 2.
+
+  It provides an easy but temporary solution, working only with Maven 3, when you can't yet write your own release profile.
diff --git a/maven-release-plugin/src/site/site.xml b/maven-release-plugin/src/site/site.xml
index a6907be5..67d10dc3 100644
--- a/maven-release-plugin/src/site/site.xml
+++ b/maven-release-plugin/src/site/site.xml
@@ -34,6 +34,7 @@ under the License.
       <item name="Introduction" href="index.html"/>
       <item name="Goals" href="plugin-info.html"/>
       <item name="Usage" href="usage.html"/>
+      <item name="Upgrade" href="upgrade.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/"/>