This is an automated email from the ASF dual-hosted git repository. hboutemy pushed a commit to branch plugin-validation-doc in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit b4108d2f4fe1282bb6d21d10d02611bb1232be66 Author: Hervé Boutemy <[email protected]> AuthorDate: Sun Oct 8 10:01:19 2023 -0300 [MNG-7811] improve plugin validation documentation --- content/markdown/docs/3.9.5/release-notes.md | 2 +- .../markdown/guides/plugins/validation/index.md | 61 +++++++++++++--------- 2 files changed, 36 insertions(+), 27 deletions(-) diff --git a/content/markdown/docs/3.9.5/release-notes.md b/content/markdown/docs/3.9.5/release-notes.md index 9b548792..b2950b51 100644 --- a/content/markdown/docs/3.9.5/release-notes.md +++ b/content/markdown/docs/3.9.5/release-notes.md @@ -51,6 +51,7 @@ The full list of changes can be found in our [issue management system][4]. * Mojos are prevented to bootstrap new instance of `RepositorySystem` (for example by using deprecated `ServiceLocator`), they should reuse `RepositorySystem` instance provided by Maven instead. See [MNG-7471](https://issues.apache.org/jira/browse/MNG-7471). * Each line in `.mvn/maven.config` is now interpreted as a single argument. That is, if the file contains multiple arguments, these must now be placed on separate lines, see [MNG-7684](https://issues.apache.org/jira/browse/MNG-7684). * System and user properties handling cleanup, see [MNG-7556](https://issues.apache.org/jira/browse/MNG-7556). As a consequence, this may introduce breakage in environments where the user properties were used to set system properties or other way around, for example see [MNG-7887](https://issues.apache.org/jira/projects/MNG/issues/MNG-7887). +* Plugins and extensions used by your build are checked against Maven supported APIs and conventions: this "plugin validation" may report WARNINGs at the end of your build. See [plugin validation documentation](../../guides/plugins/validation/) to better understand what to do when your build suffers from such warnings. ## Complete Release Notes @@ -61,4 +62,3 @@ See [complete release notes for all versions][5] [2]: https://maven.apache.org/ [4]: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316922&version=12353460 [5]: ../../docs/history.html - diff --git a/content/markdown/guides/plugins/validation/index.md b/content/markdown/guides/plugins/validation/index.md index 9504fcc6..c2a58831 100644 --- a/content/markdown/guides/plugins/validation/index.md +++ b/content/markdown/guides/plugins/validation/index.md @@ -19,56 +19,65 @@ specific language governing permissions and limitations under the License. --> -Maven since versions 3.9.x and 4.x introduced `Plugin Validation` -in order to help Maven users and Maven Plugin developers maintain theirs projects. +Maven since versions 3.9.x and 4.x introduced **Plugin Validation** +in order to help Maven users and Maven Plugin developers discover issues with the plugins they +use or maintain that may break in the future. -## Internal Plugins Validation issues +These issues are displayed as WARNING either when plugin goal is executed or at the end of the build: + +``` +[WARNING] Plugin validation issues were detected in x plugin(s) +``` + +and split in 2 categories based on what actions should be taken: + +## Internal issues Internal Plugins Validation issues (project local) are issues discovered in Maven project configuration, like: - - using deprecated plugins goals - - using deprecated plugins parameters - - using read only plugins parameters + - project using deprecated plugins goals ([MNG-7457](https://issues.apache.org/jira/browse/MNG-7457)), + - project using deprecated plugins parameters, + - project using read only plugins parameters ([MNG-7464](https://issues.apache.org/jira/browse/MNG-7464)). -In such cases users can fix their project by fixing configuration by editing their POMs. -Users should consult actual plugin documentation or try to update plugin to newer version. +In such cases, users can fix their project by fixing configuration by editing their POMs. +Users should consult actual plugin documentation (and eventually try to update plugin to newer version). -## External Plugins Validation issues +## External issues External Plugins Validation issues (non-configuration) are issues detected in plugin itself, like: - - using old, deprecated Maven Api by plugin - - declaring dependencies for Maven Core artifacts in wrong scope in plugin project + - plugin using old, deprecated Maven API, + - plugin declaring dependencies for Maven Core artifacts in wrong scope (should be `provided`). -External Plugins issues can only be fix by plugin authors. +External Plugins issues require to be fixed by plugin authors first. -In such cases users can try to update plugin to newer version. -If the newest version of plugin still has an issue users should report problem to plugin authors. +In such cases users can try to update plugin to newer version. +If the newest version of plugin still has such an issue, users should report problem to plugin authors. ## Manage Plugin Validation verbosity -In order to manage Plugin Validation verbosity a property `maven.plugin.validation` can be used. +In order to manage Plugin Validation verbosity, a system property `-Dmaven.plugin.validation=...` can be used on command line (or injected: see below). Allowed values are: - - `NONE` - mute Plugin Validation completely, nothing will be reported - - `INLINE` - report only `Internal` issues in place where occur - - `BRIEF` - report only `Internal` issues in place where occur and list of plugins with `External` issues at the and of build - - `SUMMARY` - report list of plugins with `Internal` and `External` issues at the end of build - - `VERBOSE` - report `Internal` and `External` issues at the end of build in verbose mode + - `NONE` - mute Plugin Validation completely, nothing will be reported, + - `INLINE` (default) - report only `Internal` issues in place where they occur, + - `BRIEF` - report `Internal` issues in place where they occur and list of plugins with `External` issues at the end of the build, + - `SUMMARY` - report list of plugins with `Internal` and `External` issues at the end of the build, + - `VERBOSE` - report `Internal` and `External` issues at the end of build in verbose mode. -Configuration values for `maven.plugin.validation` are case insensitive, can be used on command line, like: +Configuration values for `maven.plugin.validation` are case insensitive, can only be used on command line (not as property in POM), like: ``` mvn -Dmaven.plugin.validation=verbose ... ``` -Can be added to `MAVEN_OPTS` or `MAVEN_ARGS` environment variables, -can also be added to `.mvn/maven.config` file in order to configure per project. - -Users can add such property to their `settings.xml` file to change configuration globally. +As a consequence: +- it can be added to `MAVEN_OPTS` or `MAVEN_ARGS` environment variables, +- it can also be added to `.mvn/maven.config` file in order to configure per project, +- it can also be added as property in `settings.xml` file to change configuration globally. -*NOTICE* as `maven.plugin.validation` is configuration item for Maven itself, it can not be used in project pom.xml +But it can not be used as a user property in project `pom.xml`. Please consult: - [Configuring Apache Maven](/configure.html)
