Marking Incompatible Releases

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 now (as of version 1.322 of Jenkins and version 1.42 of maven-hpi-plugin) support for marking the oldest version which is compatible with the configuration of your plugin’s current version.

Recording the oldest compatible version

Starting with plugin parent POM 3.33, it is possible to set the hpi.compatibleSinceVersion property to define the oldest compatible version.

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

If you use an older plugin parent POM (not recommended), add the following to your plugin’s POM file:

<build>
  <plugins>
    <plugin>
      <groupId>org.jenkins-ci.tools</groupId>
      <artifactId>maven-hpi-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        <compatibleSinceVersion>1.0</compatibleSinceVersion>
      </configuration>
    </plugin>
  </plugins>
</build>

You only need to specify the maven-hpi-plugin version if your plugin’s parent POM is version 1.321 or earlier. Later versions of the plugin parent POM will get the proper maven-hpi-plugin version automatically. 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 would use the new version number.

Modifying the list of available plugin upgrades

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.