[MPMD-379] Improve upgrading notes

Author: adangel

src/site/apt/examples/upgrading-PMD-at-runtime.apt.vm

@@ -85,11 +85,11 @@ Upgrading PMD at Runtime
 
    Here's a historical overview about the default PMD version used:
 
-*--------------------------------------------------------------------------------*--------------------------------------------------*
-| <<maven-pmd-plugin>>                                                           | <<PMD>>                                          |
-*--------------------------------------------------------------------------------*--------------------------------------------------*
-| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.22.0/}3.22.0}} | {{{https://pmd.github.io/pmd-7.0.0/}7.0.0}}      |
-*--------------------------------------------------------------------------------*--------------------------------------------------*
+*--------------------------------------------------------------------------------*-----------------------------------------------------*
+| <<maven-pmd-plugin>>                                                           | <<PMD>>                                             |
+*--------------------------------------------------------------------------------*-----------------------------------------------------*
+| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.22.0/}3.22.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.0.0/}7.0.0}} |
+*--------------------------------------------------------------------------------*-----------------------------------------------------*
 | {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.21.0/}3.21.0}} | {{{https://pmd.github.io/pmd-6.55.0/}6.55.0}}    |
 *--------------------------------------------------------------------------------*--------------------------------------------------*
 | {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.20.0/}3.20.0}} | {{{https://pmd.github.io/pmd-6.53.0/}6.53.0}}    |

src/site/apt/index.apt.vm

@@ -89,15 +89,30 @@ ${project.name}
 
 * Upgrading Notes
 
-  <<Note:>> Starting with Maven PMD Plugin 3.22.0, the plugin requires PDM version 7.0.0 or higher.
-  The PMD 7.0.0 switched to the SLF4J and since Maven 3.1.0+ the SLF4J is the default logging API,
-  because of that the <<<showPmdLog>>> makes no sense to exist. See
-  {{{}https://maven.apache.org/ref/3.9.6/maven-embedder/logging.html}}Maven Logging for more details.
-
-  <<Note:>> Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized
-  into categories, e.g. <<</category/java/bestpractices.xml>>>. So when upgrading to
-  Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset.
-  See {{{./examples/usingRuleSets.html}Using Rule Sets}} for more information.
+** 3.22.0
+
+    * Starting with Maven PMD Plugin 3.22.0, the plugin requires PMD version 7.0.0 or higher.
+      PMD 7.0.0 switched to SLF4J and since Maven 3.1.0+ SLF4J is the default logging API.
+      Logs from PMD are now always shown and cannot be disabled at runtime after maven has started.
+      The property <<<showPmdLog>>> makes no sense anymore and is deprecated now. See
+      {{{https://maven.apache.org/maven-logging.html}Maven Logging}} for how to configure logging.
+      For disabling PMD logs, you'd need to start maven with <<<MAVEN_OPTS=-Dorg.slf4j.simpleLogger.log.net.sourceforge.pmd=off mvn <goals>>>>.
+
+    * The upgrade from PMD 6 to PMD 7.0.0 is a major version change. If you use the default ruleset
+      from Maven PMD Plugin, then everything should just work. But if you use a custom ruleset, you
+      most likely need to review your ruleset and migrate it to PMD 7. Rules might have been renamed or
+      replaced. See {{{https://docs.pmd-code.org/latest/pmd_release_notes_pmd7.html}Detailed Release Notes for PMD 7}}
+      and {{{https://docs.pmd-code.org/latest/pmd_userdocs_migrating_to_pmd7.html}Migration Guide for PMD 7}}.
+
+    * If you currently override the dependency to PMD ({{{./examples/upgrading-PMD-at-runtime.html}Upgrading PMD at Runtime}})
+      make sure to upgrade PMD as well to 7.0.0 or later when upgrading the Maven PMD Plugin.
+
+** 3.9.0
+
+    * Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized
+      into categories, e.g. <<</category/java/bestpractices.xml>>>. So when upgrading to
+      Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset.
+      See {{{./examples/usingRuleSets.html}Using Rule Sets}} for more information.
 
 
 * Examples