From db02f357c52f62a127431be7bb03b9bcf4f1ebf3 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Thu, 22 Feb 2024 11:54:14 +0100 Subject: [PATCH] [doc] Update maven doc, include PMD 7 usage, remove maven1 --- docs/pages/pmd/userdocs/migrating_to_pmd7.md | 26 +---- docs/pages/pmd/userdocs/tools/maven.md | 99 ++++++++++---------- docs/pages/release_notes_pmd7.md | 3 +- 3 files changed, 50 insertions(+), 78 deletions(-) diff --git a/docs/pages/pmd/userdocs/migrating_to_pmd7.md b/docs/pages/pmd/userdocs/migrating_to_pmd7.md index 30bce8c536..8dd32e1275 100644 --- a/docs/pages/pmd/userdocs/migrating_to_pmd7.md +++ b/docs/pages/pmd/userdocs/migrating_to_pmd7.md @@ -3322,31 +3322,7 @@ See the use case [I'm using only built-in rules](#im-using-only-built-in-rules) #### Maven * Due to some changes in PMD's API, you can't simply pull in the new PMD 7 dependency. -* However, there is now a compatibility module, that makes it possible to use PMD 7 with Maven. In addition to the PMD 7 - dependencies documented in [Upgrading PMD at Runtime](https://maven.apache.org/plugins/maven-pmd-plugin/examples/upgrading-PMD-at-runtime.html) - you need to add additionally the following dependency (first available version is 7.0.0-rc4): - -```xml - - net.sourceforge.pmd - pmd-compat6 - ${pmdVersion} - -``` - -It is important to add this dependency as the **first** in the list, so that maven-pmd-plugin sees the (old) -compatible versions of some classes. - -This module is available beginning with version 7.0.0-rc4 and will be there at least for the first -final version PMD 7 (7.0.0). It's not decided yet, whether we will keep updating it, after PMD 7 is finally -released. - -Note: This compatibility module only works for the built-in rules, that are still available in PMD 7. E.g. you need -to review your rulesets and look out for deprecated rules and such. See the use case -[I'm using only built-in rules](#im-using-only-built-in-rules) - -As PMD 7 revamped the Java module, if you have custom rules, you need to migrate these rules. -See the use case [I'm using custom rules](#im-using-custom-rules). +* See [Using PMD 7 with maven-pmd-plugin](pmd_userdocs_tools_maven.html#using-pmd-7-with-maven-pmd-plugin). #### Gradle diff --git a/docs/pages/pmd/userdocs/tools/maven.md b/docs/pages/pmd/userdocs/tools/maven.md index d7998bdfd4..be76561367 100644 --- a/docs/pages/pmd/userdocs/tools/maven.md +++ b/docs/pages/pmd/userdocs/tools/maven.md @@ -2,12 +2,12 @@ title: Maven PMD Plugin tags: [userdocs, tools] permalink: pmd_userdocs_tools_maven.html -last_updated: March 2020 -mpmd_version: 3.13.0 +last_updated: February 2024 +mpmd_version: 3.21.2 author: > Miguel Griffa , Romain PELISSE , - Andreas Dangel + Andreas Dangel --- ## Maven 2 and 3 @@ -239,56 +239,51 @@ Maven plugin will use and benefit from the latest bugfixes and enhancements: ``` +#### Using PMD 7 with maven-pmd-plugin + +The Maven PMD plugin comes with a specific PMD version, which is documented on the +[plugin project page](https://maven.apache.org/plugins/maven-pmd-plugin/index.html). +This might not support PMD 7 out of the box. + +Since PMD 7 is a major release which breaks compatibility in various ways, the solution described +above in [Upgrading the PMD version at runtime](#upgrading-the-pmd-version-at-runtime) doesn't work +directly. + +In order to use PMD 7 with [maven-pmd-plugin](https://maven.apache.org/plugins/maven-pmd-plugin/) a new +compatibility module has been created. This allows to use PMD 7 by simply adding one additional dependency: + +1. Follow the guide [Upgrading PMD at Runtime](https://maven.apache.org/plugins/maven-pmd-plugin/examples/upgrading-PMD-at-runtime.html) +2. Add additionally the following dependency: + +```xml + + net.sourceforge.pmd + pmd-compat6 + ${pmdVersion} + +``` + +It is important to add this dependency as the **first** in the list, so that maven-pmd-plugin sees the (old) +compatible versions of some classes. + +This module is available beginning with version 7.0.0-rc4 and will be there at least for the first +final version PMD 7 (7.0.0). It's not decided yet, whether we will keep updating it, after PMD 7 is finally +released. + +Note: This compatibility module only works for the built-in rules, that are still available in PMD 7. E.g. you need +to review your rulesets and look out for deprecated rules and such. See the use case +[I'm using only built-in rules](pmd_userdocs_migrating_to_pmd7.html#im-using-only-built-in-rules) +in the [Migration Guide for PMD 7](pmd_userdocs_migrating_to_pmd7.html). + +As PMD 7 revamped the Java module, if you have custom rules, you need to migrate these rules. +See the use case [I'm using custom rules](pmd_userdocs_migrating_to_pmd7.html#im-using-custom-rules) +in the Migration Guide. + + + + ### Reference For more information, please see the well documented PMD plugin project page here: . -Also, the bug tracker for this plugin is [here](https://issues.apache.org/jira/browse/MPMD). - - -## Maven 1 - -{% include warning.html content="Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the [announcement](http://maven.apache.org/maven-1.x-eol.html). Users are encouraged to migrate to the current version of Apache Maven." %} - -This section is about the maven 1 PMD plugin. - -### Running the pmd plugin - -#### Generating a project report - -To include the PMD report in the project reports section add the following line under -the reports element in your project.xml: - - maven-pmd-plugin - -This will add an entry to the 'project reports' section with the PMD report. - -#### Executing PMD manually - -To run PMD on a Maven project without adding it as a report, simply run - - maven pmd xdoc - -The PMD plugin writes the report in XML which will then be formatted into more readable HTML. - -### Customization - -#### Changing rulesets - -To specify a set of official, built-in rulesets to be used set them in the property -maven.pmd.rulesets. You can include this setting in your project.properties file. - -A clean strategy for customizing which rules to use for a project is to write a ruleset file. -In this file you can define which rules to use, add custom rules, and -customizing which rules to include/exclude from official rulesets. More information on -writing a ruleset can be found [here](pmd_userdocs_making_rulesets.html). - -Add to the root of your Maven project a pmd.xml file which contains the ruleset mentioned in -the previous paragraph. Add the following property to your project now: - - maven.pmd.rulesetfiles = ${basedir}/pmd.xml - -### Reference - -See the PMD plugin project page here: - +Also, the bug tracker for this plugin is [MPMD](https://issues.apache.org/jira/browse/MPMD). diff --git a/docs/pages/release_notes_pmd7.md b/docs/pages/release_notes_pmd7.md index cf71d941ff..2af4ce36d3 100644 --- a/docs/pages/release_notes_pmd7.md +++ b/docs/pages/release_notes_pmd7.md @@ -531,7 +531,7 @@ The full detailed documentation of the changes are available in the * CLI changed: Custom scripts need to be updated (`run.sh pmd ...` ➡️ `pmd check ...`, `run.sh cpd ...`, `pmd cpd ...`). * Java module revamped: Custom rules need to be updated. * Removed rules: Custom rulesets need to be reviewed. See below for a list of new and removed rules. -* XPath 1.0 support is removed, `violationSuppressXPath` now requires XPath 2.0 or 3.1: Custom rulesets need +* XPath 1.0 and 2.0 support is removed, `violationSuppressXPath` now requires XPath 3.1: Custom rulesets need to be reviewed. * Custom rules using rulechains: Need to override {% jdoc core::lang.rule.AbstractRule#buildTargetSelector() %} using {% jdoc core::lang.rule.RuleTargetSelector#forTypes(java.lang.Class,java.lang.Class...) %}. @@ -541,6 +541,7 @@ The full detailed documentation of the changes are available in the The structure inside the ZIP files stay the same, e.g. we still provide inside the binary distribution ZIP file the base directory `pmd-bin-`. +* For maven-pmd-plugin usage, see [Using PMD 7 with maven-pmd-plugin](pmd_userdocs_tools_maven.html#using-pmd-7-with-maven-pmd-plugin). ### For integrators