Skip to content

Commit

Permalink
Resolves #921: Added extended documentation on dependencyIncludes/dep…
Browse files Browse the repository at this point in the history 
…endencyExcludes with a faq section and an example
  • Loading branch information
@jarmoniuk
jarmoniuk committed May 15, 2023
1 parent 765e23f commit 0dba4e5
Show file tree
Hide file tree
Showing 4 changed files with 112 additions and 9 deletions.
16 changes: 10 additions & 6 deletions versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down
10 changes: 7 additions & 3 deletions ...s-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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>
*
Expand Down
65 changes: 65 additions & 0 deletions versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

30 changes: 30 additions & 0 deletions versions-maven-plugin/src/site/markdown/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

0 comments on commit 0dba4e5

Please sign in to comment.