From 2c838fbebb5785713e89ac7ee58e44ad2f2d7626 Mon Sep 17 00:00:00 2001 From: Andrzej Jarmoniuk Date: Mon, 15 May 2023 07:41:13 +0200 Subject: [PATCH] Resolves #921: Added extended documentation on dependencyIncludes/dependencyExcludes with a faq section and an example --- .../enforcer/MaxDependencyUpdates.java | 16 +++-- .../DisplayDependencyUpdatesMojo.java | 10 ++- .../examples/display-dependency-updates.md | 65 +++++++++++++++++++ .../src/site/markdown/faq.md | 30 +++++++++ 4 files changed, 112 insertions(+), 9 deletions(-) diff --git a/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java b/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java index 8b0fa4b001..921f2421d3 100644 --- a/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java +++ b/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java @@ -137,20 +137,24 @@ public class MaxDependencyUpdates implements EnforcerRule2 { protected boolean ignoreSubIncrementalUpdates = false; /** - * List of dependency inclusion patterns. - * Only dependencies matching all the patterns will be considered. + *

List of input dependency inclusion patterns.

+ *

Note: even if a version is specified, it will refer to the input dependency version. + * To filter output versions, please use {@link #ruleSet}.

+ *

>Only dependencies matching all the patterns will be considered. * The wildcard "*" can be used as the only, first, last or both characters in each token. - * The version token does support version ranges. + * The version token does support version ranges.

dependencyIncludes = singletonList(WILDCARD); /** - * List of dependency exclusion patterns. - * Only dependencies matching none of the patterns will be considered. + *

List of input dependency exclusion patterns.

+ *

Note: even if a version is specified, it will refer to the input dependency version. + * To filter output versions, please use {@link #ruleSet}.

+ *

Only dependencies matching none of the patterns will be considered. * The wildcard "*" can be used as the only, first, last or both characters in each token. - * The version token does support version ranges. + * The version token does support version ranges.

* * @since 2.14.0 */ diff --git a/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java b/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java index 8b86b19c0f..bb0600c730 100644 --- a/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java +++ b/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java @@ -152,7 +152,9 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo { private boolean processDependencies; /** - * Only take these artifacts into consideration. + *

Only take the specified input dependencies into account.

+ *

Note: even if a version is specified, it will refer to the input dependency version. + * To filter output versions, please use {@link #ruleSet} or {@link #ignoredVersions}.

*

* Comma-separated list of extended GAV patterns. * @@ -174,7 +176,9 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo { private List dependencyIncludes; /** - * Exclude these artifacts from consideration. + *

Do not take the specified input dependencies into account.

+ *

Note: even if a version is specified, it will refer to the input dependency version. + * To filter output versions, please use {@link #ruleSet} or {@link #ignoredVersions}.

*

* Comma-separated list of extended GAV patterns. * @@ -182,7 +186,7 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo { * Extended GAV: groupId:artifactId:version:type:classifier:scope *

*

- * The wildcard "*" can be used as the only, first, last or both characters in each token. + * The wildcaNote:rd "*" can be used as the only, first, last or both characters in each token. * The version token does support version ranges. *

* diff --git a/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md b/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md index a8af766c23..21375e9f24 100644 --- a/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md +++ b/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md @@ -55,3 +55,68 @@ Which produces the following output: [INFO] Final Memory: 10M/167M [INFO] ------------------------------------------------------------------------ ``` + +# Ignore a specific version suffix in version updates + +Let's suppose you wanted `org.apache.maven.doxia:doxia-core:` not to be updated to `2.0.0-M6` or `org.apache.maven:maven-core` to `4.0.0-alpha-5' or anything with a `-M` or `-alpha' in it. Upon first sight of the `dependencyExcludes` option, one might consider to use it to filter out anything with `2.*-M.*` or `*-alpha.*`. + +Well, that would be wrong. `dependencyIncludes` and `dependencyExcludes` work only on *input* dependencies, that is, dependency versions that are already being used by your project. This means that it is likely that you will still see the dreaded `2.0.0-M6`-like version in the updates. + +You can either use `ruleSet` or `ignoredVersions`. The former allows for a greater control where you can specify ignored version patterns per dependency whereas the latter is intended to be used from command line ans only offers simple version filters. + +So, let's say we want to display dependency updates of this very plugin and while doing so, ignore all updates with an `-M` or `-alpha` at the end of the version string, simply use: + +```shell +mvn org.codehaus.mojo:versions-maven-plugin:display-dependency-updates "-Dmaven.version.ignore=.*-M.*,.*-alpha.*" +``` + +or: + +```xml + + ... + .*-M.*,.*-alpha.* + ... + +``` + +in your project config. That will result in the following output. Instead of: + +```shell +[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin --- +[INFO] The following dependencies in Dependency Management have newer versions: +[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138 +[INFO] org.apache.maven:maven-artifact ............... 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven:maven-compat ................. 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven:maven-core ................... 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven:maven-model .................. 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven:maven-plugin-api ............. 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven:maven-settings ............... 3.2.5 -> 4.0.0-alpha-5 +[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0 +[INFO] org.apache.maven.plugin-testing:maven-plugin-testing-harness ... +[INFO] 3.3.0 -> 4.0.0-alpha-1 +[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ... +[INFO] 3.8.1 -> 3.8.2 +[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0 +[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7 +``` + +you will only see: + +```shell +[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin --- +[INFO] The following dependencies in Dependency Management have newer versions: +[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138 +[INFO] org.apache.maven:maven-artifact ....................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven:maven-compat ......................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven:maven-core ........................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven:maven-model .......................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven:maven-plugin-api ..................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven:maven-settings ....................... 3.2.5 -> 3.9.2 +[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0 +[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ... +[INFO] 3.8.1 -> 3.8.2 +[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0 +[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7 +``` + diff --git a/versions-maven-plugin/src/site/markdown/faq.md b/versions-maven-plugin/src/site/markdown/faq.md index 7367e3813a..f3c920ba51 100644 --- a/versions-maven-plugin/src/site/markdown/faq.md +++ b/versions-maven-plugin/src/site/markdown/faq.md @@ -64,3 +64,33 @@ manager. In most cases, using a repository manager will solve these issues as the repository managers usually rebuild the metadata files based on the artifacts that are present. + +### Why is a dependency version not excluded by dependencyExcludes + +`dependencyIncludes` and `dependencyExcludes` work on *input* dependencies and not on output dependencies. That will mean that even if you include a version string you don't want the given dependency to be updated to, that version might still get chosen as the target dependency version. + +The reason for that is that the option filters *input* dependency versions. + +Let's suppose you wanted `org.apache.maven.doxia:doxia-core:` not to be updated to `2.0.0-M6` or `org.apache.maven:maven-core` to `4.0.0-alpha-5' or anything with a `-M` or `-alpha' in it. Upon first sight of the `dependencyExcludes` option, one might consider to use it to filter out anything with `2.*-M.*` or `*-alpha.*`. + +Well, that would be wrong. `dependencyIncludes` and `dependencyExcludes` work only on *input* dependencies, that is, dependency versions that are already being used by your project. This means that it is likely that you will still see the dreaded `2.0.0-M6`-like version in the updates. + +Instead, what you should be looking at is `ruleSet` or `ignoredVersions`. The former allows for a greater control where you can specify ignored version patterns per dependency whereas the latter is intended to be used from command line ans only offers simple version filters. + +So, to ignore all updates with an `-M.*` at the end of the version string, simply use: + +`-Dmaven.version.ignore=.*-M.*` + +or: + +```xml + + ... + .*-M.* + ... + +``` + +in your project config. + +See [Issue #258](https://github.com/mojohaus/versions/issues/258) and [the documentation for ignoredVersions](https://www.mojohaus.org/versions/versions-maven-plugin/display-dependency-updates-mojo.html#ignoredVersions)