Mark a new plugin version as incompatible with older versions

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

The need for this should be rare. Jenkins has an automatic data format upgrade capability, which should be used whenever possible for the best user experience.

At times, changes will be made to a plugin which result in the new version of the plugin no longer being compatible with the configuration used for older versions. When this is the case, you will probably want to be sure that your plugin’s users are aware of this incompatibility. There is support for marking the oldest version which is compatible with the configuration of your plugin’s current version.

Recording Oldest Compatible Version

Starting from Plugin POM 3.33, it is possible to set a hpi.compatibleSinceVersion property to define the oldest compatible version.

<properties>
    <jenkins.version>2.289.3</jenkins.version>
    <hpi.compatibleSinceVersion>1.0</hpi.compatibleSinceVersion>
</properties>

compatibleSinceVersion should be the oldest version which is compatible with the configuration for the new version of your plugin - if your new version is not configuration-compatible with any previous versions, compatibleSinceVersion should use the next release’s version number.

You can use the same system with CD-enabled plugins.

Modification to Display of Updatable Plugin List

When a new plugin version is available as an update, and that new plugin version has a compatibleSinceVersion defined, the Update Center will check to see whether the installed version of the plugin is compatible with the new plugin. If the installed version is not configuration-compatible, the plugin will show up in the available updates list with a note, in red, that jobs may need to be reconfigured.

See below:

plugin not compatible