Update docs for Maven 4 and release option

Author: Bukama

src/site/apt/examples/set-compiler-release.apt.vm

@@ -28,15 +28,14 @@
 
 Setting the <<<--release>>> of the Java Compiler
 
-  Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
+  Starting with JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
   option to specify against which Java SE release you want to build the project.
-  For example, you have JDK 11 installed and used by Maven, but you want to
+  For example, you have JDK 17 installed and used by Maven, but you want to
   build the project against Java 8.
   The <<<--release>>> option ensures that the code is compiled following the
   rules of the programming language of the specified release, and that generated
   classes target the release as well as the public API of that release. This
-  means that, unlike the
-  {{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}},
+  means that, unlike the old <<<-source>>> and <<<-target>>> options,
   the compiler will detect and generate an error when using APIs that don't exist
   in previous releases of Java SE.
 
@@ -76,67 +75,8 @@ Setting the <<<--release>>> of the Java Compiler
 </project>
 +-----
 
-  <<Note:>> The value in the <<<release>>> parameter follows the new version naming scheme adopted
-  since Java 9. As such, the release number does not start with 1.x anymore. Also note that the
+  <<Note:>> The value in the <<<release>>> parameter follows
+  {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}} adopted since Java 9.
+  As such, the release number does not start with 1.x anymore. Also note that the
   supported <<<release>>> targets include the release of the currently used JDK plus a limited number
   of previous releases.
-
-* Usage on JDK 8
-
-  The <<<--release>>> option is not supported using JDK 8. To enable a project that targets Java 8
-  to be built using JDK 8 and also JDK 9 or later requires the conditional usage of the
-  <<<--release>>> option.
-
-  Conditional parametrization is required for the Compiler Plugin version below <<<3.13.0>>>
-  or compilerId different that <<<javac>>>.
-
-  This may be done through the use of a profile:
-
-+-----
-<project>
-  [...]
-  <profiles>
-    [...]
-    <profile>
-      <id>set-compiler-release</id>
-      <activation>
-        <jdk>[9,)</jdk>
-      </activation>
-      <properties>
-        <maven.compiler.release>8</maven.compiler.release>
-      </properties>
-    </profile>
-    [...]
-  </profiles>
-  [...]
-</project>
-+-----
-
-  Since version <<<3.13.0>>> of the Compiler Plugin together with the default <<<javac>>> compilerId you don't need conditional parametrisation of <<<release>>>.
-  The <<<release>>> parameter will only be effective for Java 9 or above, otherwise the <<<source>>> and <<<target>>> will be passed to the compiler.
-
-  So you can simply configure as:
-
-+-----
-<project>
- [...]
- <build>
-   [...]
-   <plugins>
-     <plugin>
-       <groupId>org.apache.maven.plugins</groupId>
-       <artifactId>maven-compiler-plugin</artifactId>
-       <version>${project.version}</version>
-       <configuration>
-         <release>8</release>
-         <source>8</source>
-         <target>8</target>
-       </configuration>
-     </plugin>
-   </plugins>
-   [...]
- </build>
- [...]
-</project>
-+-----
-

src/site/apt/examples/set-compiler-source-and-target.apt.vm

@@ -28,21 +28,25 @@
 
 Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
 
+  (If you're are using version <<<3.13.0>>> or newer of the Compiler Plugin, use the recommended
+  {{{../examples/set-compiler-release.html}<<<maven.compiler.release>>> property}}.)
+
   Sometimes when you may need to compile a certain project to a different
   version than what you are currently using.  The <<<javac>>> can accept
   such command using <<<-source>>> and <<<-target>>>.  The Compiler Plugin
   can also be configured to provide these options during compilation.
+  You have to set the version following {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}}.
 
-  For example, if you want to use the Java 8 language features (<<<-source 1.8>>>)
-  and also want the compiled classes to be compatible with JVM 1.8 (<<<-target 1.8>>>),
-  you can either add the two following properties, which are the default property names for the plugin parameters:
+  For example, if you want to use the Java 8 language features and also want the compiled classes to be compatible
+  with JVM 8 (former 1.8) you can either add the two following properties, which are the default property names
+  for the plugin parameters:
 
 +-----
 <project>
   [...]
   <properties>
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>8</maven.compiler.source>
+    <maven.compiler.target>8</maven.compiler.target>
   </properties>
   [...]
 </project>
@@ -61,8 +65,8 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
         <artifactId>maven-compiler-plugin</artifactId>
         <version>${project.version}</version>
         <configuration>
-          <source>1.8</source>
-          <target>1.8</target>
+          <source>8</source>
+          <target>8</target>
         </configuration>
       </plugin>
     </plugins>
@@ -79,6 +83,9 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
   {{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}}
   to verify your code doesn't use unintended APIs, or better yet use the
   {{{../examples/set-compiler-release.html}<<<release>>> option supported since JDK 9}}.
+  Since plugin version <<<3.13.0>>> you can use the <<<release>>> property also on JDK 8.
+  The compiler plugin will convert it to <<<source>>> and <<<target>>> automatically.
+
   In the same way, setting the <<<source>>> option does not guarantee that your code actually compiles on a JDK with
   the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven,
   refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.

src/site/apt/index.apt.vm

@@ -29,8 +29,13 @@
 ${project.name}
 
   The Compiler Plugin is used to compile the sources of your project. The
-  default compiler used to compile Java sources is javax.tools.JavaCompiler.
-  Other compilers than <<<javac>>> can be used.
+  default compiler used to compile Java sources is <<<javac>>>.
+  If you want to use another compiler, refer to the {{{./non-javac-compilers.html} guide: Using Non-Javac Compilers}}.
+
+  At present the default <<<source>>> and the default <<<target>>>
+  setting are both <<<8>>>, independently of the JDK you run Maven with.
+  You are highly encouraged to change these defaults by setting the <<<release>>> option as described in the
+  {{{./examples/set-compiler-release.html}guide: Compile Using The <<<--release>>> javac Option}}.
 
   <<NOTE:>> <To know more about the JDK javac, please see:
   {{https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html}}.>
@@ -70,11 +75,9 @@ ${project.name}
   To provide you with better understanding on some usages of the Compiler
   Plugin, you can take a look into the following examples:
 
-  * {{{./examples/compile-using-different-jdk.html}Compile Using A Different JDK}}
-
-  * {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
+  * {{{./examples/compile-using-different-jdk.html}Compile using A Different JDK}}
 
-  * {{{./examples/set-compiler-release.html}Compile Using the --release javac Option (supported since JDK 9)}}
+  * {{{./examples/set-compiler-release.html}Compile Using The --release javac Option}}
 
   * {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}}
 

src/site/site.xml

@@ -34,8 +34,7 @@ under the License.
     </menu>
     <menu name="Examples">
       <item name="Compile Using A Different JDK" href="examples/compile-using-different-jdk.html"/>
-      <item name="Compile Using -source and -target javac Options" href="examples/set-compiler-source-and-target.html"/>
-      <item name="Compile Using the --release javac Option (JDK 9+)" href="examples/set-compiler-release.html"/>
+      <item name="Compile Using the --release javac Option" href="examples/set-compiler-release.html"/>
       <item name="Compile Using Memory Allocation Enhancements" href="examples/compile-with-memory-enhancements.html"/>
       <item name="Pass Compiler Arguments" href="examples/pass-compiler-arguments.html"/>
       <item name="Non-javac compilerIds" href="non-javac-compilers.html"/>