Note:This goal should be used as a Maven report.
Full name:
org.revapi:revapi-maven-plugin:0.12.1:report
Description:
Attributes:
| Name | Type | Since | Description |
|---|---|---|---|
| alwaysCheckForReleaseVersion | boolean | 0.1 | If true (the default) revapi will always download the information
about the latest version from the remote repositories (instead of
using locally cached info). This will respect the offline settings. Default value is: true. User property is: revapi.alwaysCheckForReleaseVersion. |
| analysisConfiguration | PlexusConfiguration | 0.1 | The JSON or XML configuration of various analysis options. The
available options depend on what analyzers are present on the
plugin classpath through the
<dependencies>. Consult configuration documentation
for more details.
These settings take precedence over the configuration loaded from analysisConfigurationFiles. |
| analysisConfigurationFiles | Object[] | 0.1 | The list of files containing the configuration of various analysis
options. The available options depend on what analyzers are present
on the plugins classpath through the
<dependencies>.
The analysisConfiguration can override the settings present in the files. The list is either a list of strings or has the following form:
<analysisConfigurationFiles>
<configurationFile>
<path>path/to/the/file/relative/to/project/base/dir</path>
<resource>path/to/the/file/in/one/of/the/dependencies</resource>
<roots>
<root>configuration/root1</root>
<root>configuration/root2</root>
...
</roots>
</configurationFile>
...
</analysisConfigurationFiles>
An example of this might be a config file which contains API changes to be ignored in all past versions of a library. The classes to be ignored are specified in a configuration that is specific for each version:
{
"0.1.0" : [
{
"extension": "revapi.ignore",
"configuration": [
{
"code" : "java.method.addedToInterface",
"new" : "method void com.example.MyInterface::newMethod()",
"justification" : "This interface is not supposed to be implemented by clients."
},
...
]
}
],
"0.2.0" : [
...
]
}
User property is: revapi.analysisConfigurationFiles. |
| checkDependencies | boolean | 0.1 | Whether to include the dependencies in the API checks. This is the
default thing to do because your API might be exposing classes from
the dependencies and thus classes from your dependencies could
become part of your API.
However, setting this to false might be useful in situations where you have checked your dependencies in another module and don't want do that again. In that case, you might want to configure Revapi to ignore missing classes because it might find the classes from your dependencies as used in your API and would complain that it could not find it. See the docs. Default value is: true. User property is: revapi.checkDependencies. |
| disallowedExtensions | String | 0.1 | A comma-separated list of extensions (fully-qualified class names
thereof) that are not taken into account during API analysis. By
default, all extensions that are found on the classpath are used.
You can modify this set if you use another extensions that change the found differences in a way that the determined new version would not correspond to what it should be. User property is: revapi.disallowedExtensions. |
| expandProperties | boolean | 0.11.6 | If set to true, the Maven properties will be expanded in the
configuration before it is supplied to Revapi. I.e. any
${var} appearing in the configuration values
will be replaced with the value of the var property as
known to Maven. If the property is not defined, the expansion
doesn't take place. Default value is: false. User property is: revapi.expandProperties. |
| failOnMissingConfigurationFiles | boolean | 0.1 | Set to false if you want to tolerate files referenced in the
analysisConfigurationFiles missing on the filesystem
and therefore not contributing to the analysis configuration.
The default is true, which means that a missing analysis configuration file will fail the build. Default value is: true. User property is: revapi.failOnMissingConfigurationFiles. |
| failOnUnresolvedArtifacts | boolean | 0.1 | If true, the build will fail if one of the old or new artifacts
fails to be resolved. Defaults to false. Default value is: false. User property is: revapi.failOnUnresolvedArtifacts. |
| failOnUnresolvedDependencies | boolean | 0.1 | If true, the build will fail if some of the dependencies of the old
or new artifacts fail to be resolved. Defaults to false. Default value is: false. User property is: revapi.failOnUnresolvedDependencies. |
| generateSiteReport | boolean | 0.1 | Set this to false if you want to use the goal to generate other
kind of output than the default report for the Maven-generated
site. You can generate such output by using different reporting
extensions (like revapi-reporter-text). Default value is: true. User property is: revapi.generateSiteReport. |
| newArtifacts | String[] | 0.1 | The coordinates of the new artifacts. These are the full GAVs of
the artifacts, which means that you can compare different artifacts
than the one being built. If you merely want to specify the
artifact being built, use newVersion property instead. User property is: revapi.newArtifacts. |
| newVersion | String | 0.1 | The new version of the artifact. Defaults to "${project.version}". Default value is: ${project.version}. User property is: revapi.newVersion. |
| oldArtifacts | String[] | 0.1 | The coordinates of the old artifacts. Defaults to single artifact
with the latest released version of the current project. If the
this property is null, the oldVersion property is
checked for a value of the old version of the artifact being built. User property is: revapi.oldArtifacts. |
| oldVersion | String | 0.1 | If you don't want to compare a different artifact than the one
being built, specifying the just the old version is simpler way of
specifying the old artifact. The default value is "RELEASE" meaning
that the old version is the last released version of the artifact
being built. Default value is: RELEASE. User property is: revapi.oldVersion. |
| pipelineConfiguration | PlexusConfiguration | 0.11.0 | The JSON or XML configuration of the extensions pipeline. This
enables the users easily specify which extensions should be
included/excluded in the Revapi analysis pipeline and also to
define transformation blocks - a way of grouping transforms
together to enable more fine grained control over how differences
are transformed. |
| reportCriticality | String | 0.1 | The minimum criticality of the differences that should be included
in the report. This has to be one of the criticalities configured
in the pipeline configuration (if the pipeline configuration
doesn't define any, the following are the default ones:
allowed, documented,
highlight, error). If not defined, the
value is derived from reportSeverity using the
severity-to-criticality mapping (which is again configured in the
pipeline configuration. If not defined in the pipeline
configuration explicitly, the default mapping is the following:
EQUIVALENT = allowed,
NON_BREAKING = documented,
POTENTIALLY_BREAKING = error,
BREAKING = error. User property is: revapi.minimumCriticality. |
| reportSeverity | FailSeverity | 0.1 | Deprecated. use reportCriticality instead Default value is: potentiallyBreaking. User property is: revapi.reportSeverity. |
| resolveProvidedDependencies | boolean | 0.1 | When establishing the API classes, Revapi by default also looks
through the provided dependencies. The reason for this
is that even though such dependencies do not appear in the
transitive dependency set established by maven, they need to be
present both on the compilation and runtime classpath of the
module. Therefore, the classes in the module are free to expose
classes from a provided dependency as API elements.
In rare circumstances this is not a desired behavior though. It is undesired if for example the classes from the provided dependency are used only for establishing desired build order or when they are used in some non-standard scenarios during the build and actually not needed at runtime. Note that this property only influences the resolution of provided dependencies of the main artifacts, not the transitively reachable provided dependencies. For those, use the resolveTransitiveProvidedDependencies parameter. Default value is: true. User property is: revapi.resolveProvidedDependencies. |
| resolveTransitiveProvidedDependencies | boolean | 0.1 | In addition to resolveProvidedDependencies this
property further controls how provided dependencies are resolved.
Using this property you can control how the indirect, transitively
reachable, provided dependencies are treated. The default is to not
consider them, which is almost always the right thing to do. It
might be necessary to set this property to true in the
rare circumstances where the API of the main artifacts includes
types from such transitively included provided dependencies. Such
occurrence will manifest itself by Revapi considering such types as
missing (which is by default reported as a potentially breaking
change). When you then resolve the transitive provided dependencies
(by setting this parameter to true), Revapi will be able to find
such types and do a proper analysis of them. Default value is: false. User property is: revapi.resolveTransitiveProvidedDependencies. |
| skip | boolean | 0.1 | Whether to skip the mojo execution. Default value is: false. User property is: revapi.skip. |
| versionFormat | String | 0.1 | If set, this property demands a format of the version string when
the oldVersion or newVersion parameters
are set to RELEASE or LATEST special
version strings.
Because Maven will report the newest non-snapshot version as the latest release, we might end up comparing a .Beta or other pre-release versions with the new version. This might not be what you want and setting the versionFormat will make sure that a newest version conforming to the version format is used instead of the one resolved by Maven by default. This parameter is a regular expression pattern that the version string needs to match in order to be considered a RELEASE. User property is: revapi.versionFormat. |
These settings take precedence over the configuration loaded from analysisConfigurationFiles.
The analysisConfiguration can override the settings present in the files.
The list is either a list of strings or has the following form:
<analysisConfigurationFiles>
<configurationFile>
<path>path/to/the/file/relative/to/project/base/dir</path>
<resource>path/to/the/file/in/one/of/the/dependencies</resource>
<roots>
<root>configuration/root1</root>
<root>configuration/root2</root>
...
</roots>
</configurationFile>
...
</analysisConfigurationFiles>
An example of this might be a config file which contains API changes to be ignored in all past versions of a library. The classes to be ignored are specified in a configuration that is specific for each version:
{
"0.1.0" : [
{
"extension": "revapi.ignore",
"configuration": [
{
"code" : "java.method.addedToInterface",
"new" : "method void com.example.MyInterface::newMethod()",
"justification" : "This interface is not supposed to be implemented by clients."
},
...
]
}
],
"0.2.0" : [
...
]
}
However, setting this to false might be useful in situations where you have checked your dependencies in another module and don't want do that again. In that case, you might want to configure Revapi to ignore missing classes because it might find the classes from your dependencies as used in your API and would complain that it could not find it. See the docs.
You can modify this set if you use another extensions that change the found differences in a way that the determined new version would not correspond to what it should be.
failOnMissingConfigurationFiles:
The default is true, which means that a missing analysis configuration file will fail the build.
In rare circumstances this is not a desired behavior though. It is undesired if for example the classes from the provided dependency are used only for establishing desired build order or when they are used in some non-standard scenarios during the build and actually not needed at runtime.
Note that this property only influences the resolution of provided dependencies of the main artifacts, not the transitively reachable provided dependencies. For those, use the resolveTransitiveProvidedDependencies parameter.
resolveTransitiveProvidedDependencies:
skip:
Because Maven will report the newest non-snapshot version as the latest release, we might end up comparing a .Beta or other pre-release versions with the new version. This might not be what you want and setting the versionFormat will make sure that a newest version conforming to the version format is used instead of the one resolved by Maven by default.
This parameter is a regular expression pattern that the version string needs to match in order to be considered a RELEASE.