Resolves #921: Clarify dependencyIncludes/dependencyExcludes

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.
+     * <p>List of <u>input</u> dependency inclusion patterns.</p>
+     * <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
+     * To filter <u>output</u> versions, please use {@link #ruleSet}.</p>
+     * <p>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.</p>
      *
      * @since 2.14.0
      */
     protected List<String> dependencyIncludes = singletonList(WILDCARD);
 
     /**
-     * List of dependency exclusion patterns.
-     * Only dependencies matching none of the patterns will be considered.
+     * <p>List of <u>input</u> dependency exclusion patterns.</p>
+     * <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
+     * To filter <u>output</u> versions, please use {@link #ruleSet}.</p>
+     * <p>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.</p>
      *
      * @since 2.14.0
      */

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.
+     * <p>Only take the specified <u>input</u> dependencies into account.</p>
+     * <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
+     * To filter <u>output</u> versions, please use {@link #ruleSet} or {@link #ignoredVersions}.</p>
      * <p>
      * Comma-separated list of extended GAV patterns.
      *
@@ -174,15 +176,17 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
     private List<String> dependencyIncludes;
 
     /**
-     * Exclude these artifacts from consideration.
+     * <p>Do not take the specified <u>input</u> dependencies into account.</p>
+     * <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
+     * To filter <u>output</u> versions, please use {@link #ruleSet} or {@link #ignoredVersions}.</p>
      * <p>
      * Comma-separated list of extended GAV patterns.
      *
      * <p>
      * Extended GAV: groupId:artifactId:version:type:classifier:scope
      * </p>
      * <p>
-     * The wildcard "*" can be used as the only, first, last or both characters in each token.
+     * The wildca<u>Note:</u>rd "*" can be used as the only, first, last or both characters in each token.
      * The version token does support version ranges.
      * </p>
      *

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
+<configuration>
+    ...
+    <ignoredVersions>.*-M.*,.*-alpha.*</ignoredVersions>
+    ...
+</configuration>
+```
+
+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
+```
+

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 <u>output</u> 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
+<configuration>
+    ...
+    <ignoredVersions>.*-M.*</ignoredVersions>
+    ...
+</configuration>
+```
+
+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)