Jenkins : Marking a new plugin version as incompatible with older versions

Plugin Changes Causing Incompatibility

The need for this should be rare.  Hudson 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 Hudson and version 1.42 of the maven-hpi-plugin) 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.60.3</jenkins.version>
    <java.level>8</java.level>
    <hpi.compatibleSinceVersion>1.0</hpi.compatibleSinceVersion>
  </properties>

If you use older Plugin POMs (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 POM's parent 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.

Modification to Display of Updateable 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:

  • since Jenkins 1.564

Attachments: