revapi:update-release-properties

Full name:

org.revapi:revapi-maven-plugin:0.14.3:update-release-properties

Description:

(no description)

Attributes:

  • Requires a Maven project to be executed.
  • Executes by direct invocation only.
  • Since version: 0.4.0.
  • Invokes the execution of the lifecycle phase package prior to executing itself.

Optional Parameters

Name Type Since Description
<alwaysCheckForReleaseVersion> boolean 0.4.0 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.4.0 The JSON or XML configuration of various analysis options. The available options depend on what analyzers are present on the plugin classpath through the &lt;dependencies&gt;. Consult configuration documentation for more details.

These settings take precedence over the configuration loaded from analysisConfigurationFiles.


<analysisConfigurationFiles> Object[] 0.4.0 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 &lt;dependencies&gt;.

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>

where
  • path is the path on the filesystem,
  • resource is the path to the resource file in one of the artifacts the plugin depends on
  • roots is optional and specifies the subtrees of the JSON/XML config that should be used for configuration. If not specified, the whole file is taken into account.
Either path or resource has to be specified but not both. The configuration/root1 and configuration/root2 are paths to the roots of the configuration inside that JSON/XML config file. This might be used in cases where multiple configurations are stored within a single file and you want to use a particular one.

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.4.0 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.4.0 A comma-separated list of extensions (fully-qualified class names thereof) that are not taken into account during API analysis for versioning purposes. By default, only the semver-ignore transform is not taken into account so that it does not interfere with the purpose of modifying the version based on the semver rules.

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.


Default value is: org.revapi.basic.SemverIgnoreTransform.
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.
<failBuildOnProblemsFound> boolean 0.4.0 If true (the default), the maven plugin will fail the build when it finds API problems (e.g. problems with with the criticality at least equal to failCriticality).
Default value is: true.
User property is: revapi.failBuildOnProblemsFound.
<failCriticality> String 0.12.0 The minimum criticality of the found differences at which to fail the build. 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 failSeverity 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.maximumCriticality.
<failOnMissingConfigurationFiles> boolean 0.4.0 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.4.0 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.4.0 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.
<failSeverity> FailSeverity 0.4.0 Deprecated. use the new failCriticality
Default value is: potentiallyBreaking.
User property is: revapi.failSeverity.
<forceVersionUpdate> boolean 0.4.0 When the pom.xml of the updated project contains no version and the computed version is different from the inherited version, the goal fails by default so that it doesn't change the version inheritance used by the projects. If you want to set an explicit version to such projects, set this property to true.
Default value is: false.
User property is: revapi.forceVersionUpdate.
<newArtifacts> String[] 0.4.0 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.
<newPromotedDependencies> PromotedDependency[] 0.13.6 A list of dependencies of the new artifact(s) that should be considered part of the new API.
<newVersion> String 0.4.0 The new version of the artifact. Defaults to "${project.version}".
Default value is: ${project.version}.
User property is: revapi.newVersion.
<oldArtifacts> String[] 0.4.0 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.
<oldPromotedDependencies> PromotedDependency[] 0.13.6 A list of dependencies of the old artifact(s) that should be considered part of the old API.
<oldVersion> String 0.4.0 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 (either remote or found locally (to account for artifacts installed into the local repo that are not available in some public remote repository)). The version of the compared artifact will be strictly older than the version of the new artifact.

If you specify "LATEST", the old version will be resolved to the newest version available remotely, including snapshots (if found in one of the repositories active in the build). The version of the compared artifact will be either older or equal to the version of the new artifact in this case to account for comparing a locally built snapshot against the latest published snapshot.


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.
<preserveNewerVersion> boolean 0.13.5 If the module has a newer version than strictly required (given the amount of change since the last release and the semver rules), should the newer version be kept or reset to the lowest strictly required?
Default value is: true.
User property is: revapi.preserveNewerVersion.
<promotedDependencies> PromotedDependency[] 0.13.6 A list of dependencies of both the old and new artifact(s) that should be considered part of the old/new API. This is a convenience property if you just need to specify a set of dependencies to promote into the API and that set can be specified in a way common to both old and new APIs. If you need to specify different sets for the old and new, use oldPromotedDependencies or newPromotedDependencies respectively. If oldPromotedDependencies or newPromotedDependencies are specified, they override whatever is specified using this property.

The individual properties of the dependency (e.g. groupId, artifactId, version, type or classifier) are matched exactly. If you enclose the value in forward slashes, they are matched as regular expressions instead.

E.g. <groupId>com.acme</groupId> will only match dependencies with that exact groupId, while <groupId>/com\.acme(\..*)?/</groupId> will match "com.acme" groupId or any "sub-groupId" thereof (e.g. "com.acme.utils", etc.) using a regular expression.


<releaseVersionSuffix> String 0.4.0 The suffix to add to the release version, e.g. ".GA", ".Final", "-release". Must include some kind of separator as the first character.
User property is: revapi.releaseVersionSuffix.
<resolveProvidedDependencies> boolean 0.4.0 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.4.0 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.
<singleVersionForAllModules> boolean 0.4.0 Set to true if all the projects in the current build should share a single version (the default is false). This is useful if your distribution consists of several modules that make up one logical unit that is always versioned the same.

In this case all the projects in the current build are API-checked and the version is determined by the "biggest" API change found in all the projects. I.e. if just a single module breaks API then all of the modules will get the major version incremented.


Default value is: false.
User property is: revapi.singleVersionForAllModules.
<skip> boolean 0.4.0 Whether to skip the mojo execution.
Default value is: false.
User property is: revapi.skip.
<versionFormat> String 0.4.0 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.

Parameter Details

<alwaysCheckForReleaseVersion>

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.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.alwaysCheckForReleaseVersion
  • Default: true

<analysisConfiguration>

The JSON or XML configuration of various analysis options. The available options depend on what analyzers are present on the plugin classpath through the &lt;dependencies&gt;. Consult configuration documentation for more details.

These settings take precedence over the configuration loaded from analysisConfigurationFiles.

  • Type: org.codehaus.plexus.configuration.PlexusConfiguration
  • Since: 0.4.0
  • Required: No

<analysisConfigurationFiles>

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 &lt;dependencies&gt;.

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>

where
  • path is the path on the filesystem,
  • resource is the path to the resource file in one of the artifacts the plugin depends on
  • roots is optional and specifies the subtrees of the JSON/XML config that should be used for configuration. If not specified, the whole file is taken into account.
Either path or resource has to be specified but not both. The configuration/root1 and configuration/root2 are paths to the roots of the configuration inside that JSON/XML config file. This might be used in cases where multiple configurations are stored within a single file and you want to use a particular one.

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" : [
            ...
        ]
    }

  • Type: java.lang.Object[]
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.analysisConfigurationFiles

<checkDependencies>

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.

  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.checkDependencies
  • Default: true

<disallowedExtensions>

A comma-separated list of extensions (fully-qualified class names thereof) that are not taken into account during API analysis for versioning purposes. By default, only the semver-ignore transform is not taken into account so that it does not interfere with the purpose of modifying the version based on the semver rules.

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.

  • Type: java.lang.String
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.disallowedExtensions
  • Default: org.revapi.basic.SemverIgnoreTransform

<expandProperties>

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.
  • Type: boolean
  • Since: 0.11.6
  • Required: No
  • User Property: revapi.expandProperties
  • Default: false

<failBuildOnProblemsFound>

If true (the default), the maven plugin will fail the build when it finds API problems (e.g. problems with with the criticality at least equal to failCriticality).
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.failBuildOnProblemsFound
  • Default: true

<failCriticality>

The minimum criticality of the found differences at which to fail the build. 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 failSeverity 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.
  • Type: java.lang.String
  • Since: 0.12.0
  • Required: No
  • User Property: revapi.maximumCriticality

<failOnMissingConfigurationFiles>

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.

  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.failOnMissingConfigurationFiles
  • Default: true

<failOnUnresolvedArtifacts>

If true, the build will fail if one of the old or new artifacts fails to be resolved. Defaults to false.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.failOnUnresolvedArtifacts
  • Default: false

<failOnUnresolvedDependencies>

If true, the build will fail if some of the dependencies of the old or new artifacts fail to be resolved. Defaults to false.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.failOnUnresolvedDependencies
  • Default: false

<failSeverity>

Deprecated. use the new failCriticality
The severity of found problems at which to break the build. Defaults to potentiallyBreaking. Possible values: equivalent, nonBreaking, potentiallyBreaking, breaking.
  • Type: org.revapi.maven.FailSeverity
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.failSeverity
  • Default: potentiallyBreaking

<forceVersionUpdate>

When the pom.xml of the updated project contains no version and the computed version is different from the inherited version, the goal fails by default so that it doesn't change the version inheritance used by the projects. If you want to set an explicit version to such projects, set this property to true.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.forceVersionUpdate
  • Default: false

<newArtifacts>

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.
  • Type: java.lang.String[]
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.newArtifacts

<newPromotedDependencies>

A list of dependencies of the new artifact(s) that should be considered part of the new API.
  • Type: org.revapi.maven.PromotedDependency[]
  • Since: 0.13.6
  • Required: No

<newVersion>

The new version of the artifact. Defaults to "${project.version}".
  • Type: java.lang.String
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.newVersion
  • Default: ${project.version}

<oldArtifacts>

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.

  • Type: java.lang.String[]
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.oldArtifacts

<oldPromotedDependencies>

A list of dependencies of the old artifact(s) that should be considered part of the old API.
  • Type: org.revapi.maven.PromotedDependency[]
  • Since: 0.13.6
  • Required: No

<oldVersion>

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 (either remote or found locally (to account for artifacts installed into the local repo that are not available in some public remote repository)). The version of the compared artifact will be strictly older than the version of the new artifact.

If you specify "LATEST", the old version will be resolved to the newest version available remotely, including snapshots (if found in one of the repositories active in the build). The version of the compared artifact will be either older or equal to the version of the new artifact in this case to account for comparing a locally built snapshot against the latest published snapshot.

  • Type: java.lang.String
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.oldVersion
  • Default: RELEASE

<pipelineConfiguration>

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.
  • Type: org.codehaus.plexus.configuration.PlexusConfiguration
  • Since: 0.11.0
  • Required: No

<preserveNewerVersion>

If the module has a newer version than strictly required (given the amount of change since the last release and the semver rules), should the newer version be kept or reset to the lowest strictly required?
  • Type: boolean
  • Since: 0.13.5
  • Required: No
  • User Property: revapi.preserveNewerVersion
  • Default: true

<promotedDependencies>

A list of dependencies of both the old and new artifact(s) that should be considered part of the old/new API. This is a convenience property if you just need to specify a set of dependencies to promote into the API and that set can be specified in a way common to both old and new APIs. If you need to specify different sets for the old and new, use oldPromotedDependencies or newPromotedDependencies respectively. If oldPromotedDependencies or newPromotedDependencies are specified, they override whatever is specified using this property.

The individual properties of the dependency (e.g. groupId, artifactId, version, type or classifier) are matched exactly. If you enclose the value in forward slashes, they are matched as regular expressions instead.

E.g. <groupId>com.acme</groupId> will only match dependencies with that exact groupId, while <groupId>/com\.acme(\..*)?/</groupId> will match "com.acme" groupId or any "sub-groupId" thereof (e.g. "com.acme.utils", etc.) using a regular expression.

  • Type: org.revapi.maven.PromotedDependency[]
  • Since: 0.13.6
  • Required: No

<releaseVersionSuffix>

The suffix to add to the release version, e.g. ".GA", ".Final", "-release". Must include some kind of separator as the first character.
  • Type: java.lang.String
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.releaseVersionSuffix

<resolveProvidedDependencies>

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.

  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.resolveProvidedDependencies
  • Default: true

<resolveTransitiveProvidedDependencies>

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.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.resolveTransitiveProvidedDependencies
  • Default: false

<singleVersionForAllModules>

Set to true if all the projects in the current build should share a single version (the default is false). This is useful if your distribution consists of several modules that make up one logical unit that is always versioned the same.

In this case all the projects in the current build are API-checked and the version is determined by the "biggest" API change found in all the projects. I.e. if just a single module breaks API then all of the modules will get the major version incremented.

  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.singleVersionForAllModules
  • Default: false

<skip>

Whether to skip the mojo execution.
  • Type: boolean
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.skip
  • Default: false

<versionFormat>

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.

  • Type: java.lang.String
  • Since: 0.4.0
  • Required: No
  • User Property: revapi.versionFormat