How to introduce new plugin variable with default value without breaking compatibility

[Robin Jansohn]

I've recently taken over the deploy-plugin and bundled a new version. One of the commits that was included in the new version added a new variable called path which should later be used as an additional configuration option to overwrite the default context path. Here's the commit:

https://github.com/jenkinsci/deploy-plugin/commit/db254d7c8c70214c7da91308c50bedb25fbf4eb8#diff-b2a541c8af2e6626b795634cc9d7143dR48

The problem is that this caused a breaking change for users using the new plugin with their existing freestyle jobs:

https://issues.jenkins-ci.org/browse/JENKINS-58667

The problem is that the job config is not automatically updated and the following builds do not have the new variable populated with the default value but are instead null.

Not updated config which causes the failure:

<publishers>
  <hudson.plugins.deploy.DeployPublisher plugin="dep...@1.13">
    <adapters>
      <hudson.plugins.deploy.tomcat.Tomcat7xAdapter>
        <credentialsId>tomcat-credentials</credentialsId>
        <url>https://tomcat.internal.com:8120</url>
      </hudson.plugins.deploy.tomcat.Tomcat7xAdapter>
    </adapters>
    <contextPath></contextPath>
    <war>target/*.war</war>
    <onFailure>false</onFailure>
  </hudson.plugins.deploy.DeployPublisher>
</publishers>

The only way to fix this seems to be to force an update of the job config by simply clicking Configure->Save. This updates the job config and everything works smoothly (see the additional path element):

<publishers>
  <hudson.plugins.deploy.DeployPublisher plugin="dep...@1.14">
    <adapters>
      <hudson.plugins.deploy.tomcat.Tomcat7xAdapter>
        <credentialsId>tomcat-credentials</credentialsId>
        <url>https://tomcat.internal.com:8120</url>
        <path>/manager/text</path>
      </hudson.plugins.deploy.tomcat.Tomcat7xAdapter>
    </adapters>
    <war>target/*.war</war>
    <onFailure>false</onFailure>
  </hudson.plugins.deploy.DeployPublisher>
</publishers>

So my question is: Can this sort of problem be avoided/fixed? What is the proposed way to introduce new plugin variables with default values without breaking the job builds?

[Jesse Glick]

On Tue, Jul 30, 2019 at 10:03 AM 'Robin Jansohn' via Jenkins
Developers <jenkin...@googlegroups.com> wrote:
> Can this sort of problem be avoided/fixed?

You can replace uses of `path` with a getter returning `path != null ?
path : "/manager/text"`. Or you can add a

private Object readResolve() {
if (path == null) {
path = "/manager/text";
}
return this;
}

which will do the same but also ensure that if the configuration is
opened and resaved that a legal value for `path` will be written.

Besides checking for null you may need to check for `path.isEmpty()`,
in case the bad commit has already been released and some users who
resaved the form without touching this field may have `config.xml`
files with

<path></path>

if that is in fact not a legal value.