[JENKINS-31035] Introduce a policy for API deprecation

Problem definition

Currently, we have no backward compatibility policy besides "compatibility matters". With 1000+ plugins and basically the entire core being available to plugins, a lot of difficult or impossible to remove cruft has accumulated over the last ten years. This limits both what can be changed in core, and makes documentation difficult to use for plugin developers.

Elaborate solutions such as the bytecode compatibility transformer currently (Oct 2015) introduce difficult to investigate bugs that result in things breaking for users.

Proposal

Limit the availability in APIs (classes, methods, fields, …) provided by core to a number of releases. Depending on the feature, this can range from a few months, to a few years (e.g. two years being about 100 releases of Jenkins and eight LTS baselines).

This deprecation policy needs to be supported by tools that check publicly accessible plugins for access to deprecated (or to-be-deprecated) APIs and generate reports on them to inform deprecation policy decisions.

Ideally, Jenkins core will be enhanced to include the capability to check both plugins for use of removed APIs, so it can refuse to load plugins considered incompatible with the running Jenkins version, and the update site generation should be improved to exclude plugins that are known incompatible with the core release downloading the plugin information.

Impact

The impact of this change is not currently known both due to the large number of deprecated APIs and because we don't currently have the tooling above.

Removal of APIs needs to be done carefully (rather than wholesale), and affected, open-source plugins hosted by the Jenkins project need to be fixed to no longer rely on those APIs. This will force users to update affected plugins when updating Jenkins itself (which may be inconvenient if the new plugin release not using deprecated APIs is not compatible with the previously installed version), but it should at least ensure continued operation of their plugins.

This change may increase the frequency by which new plugin versions require newer core releases to run, as the replacement APIs may be new to the release that deprecated the existing API.

Open questions

How long is the deprecation period before an API gets removed?
- Should the same duration be used for all deprecations, or should it depend on the specific API?
  - If the latter, what are the lower/upper bounds, if any, of the deprecation period before removal?
What steps need to be followed to define a removal date for an API? Examples:
1. Provide a list of affected plugins and propose how they can be fixed? (618 plugins are using a deprecated api among which a large number are only using Hudson.getInstance() or Plugin(), see details here. evernat)
2. Provide a list of affected plugins and fix them (possibly including releases)?
3. Public announcements of API removal?
4. Documentation (Javadoc) updates?
5. Add an annotation to the removed element to allow automated processing?
Who fixes the plugins?
- Have a team responsible for finding & fixing failures, if necessary incrementing the plugin’s baseline version to get access to the replacement?
Is it worth to automate the refactoring?
How to handle previously deprecated methods? (Especially if we plan to remove them all simultaneously)

Implementation work

Annotations for deprecated methods/classes/fields that indicate their expiration date/release in a standardized manner
plugin-compat-tester needs to be extended to determine use of deprecated, to-be-removed, and/or removed API?
Extend Jenkins itself to detect use of removed APIs in plugins while they're being loaded and don't load plugins that do that?
Extend update center generation to not provide plugins that are known to use APIs removed in the version the update center is generated for?
Idea: Introduce a facility to the Jenkins plugin/update system allowing us to declare that a specific version of the plugin is the first known to be compatible with a specific version of a (core or plugin) dependency. If you attempt to upgrade the dependency you will be blocked unless you also agree to update the dependent.

Participants

LTS team
possibly a new team? Core team?

References

https://groups.google.com/forum/#!msg/jenkinsci-dev/GRimfBRGrhY/9APHtWMICwAJ
*Backward compatibility policy proposal wiki page

Originally reported by olivergondza, imported from: Introduce a policy for API deprecation

status: Open
priority: Critical
component(s): core
label(s): 2.0-rejected, api, evergreen
resolution: Unresolved
votes: 9
watchers: 18
imported: 2025-11-24

Raw content of original issue

Problem definition

Currently, we have no backward compatibility policy besides "compatibility matters". With 1000+ plugins and basically the entire core being available to plugins, a lot of difficult or impossible to remove cruft has accumulated over the last ten years. This limits both what can be changed in core, and makes documentation difficult to use for plugin developers.

Elaborate solutions such as the bytecode compatibility transformer currently (Oct 2015) introduce difficult to investigate bugs that result in things breaking for users.

Proposal

Limit the availability in APIs (classes, methods, fields, …) provided by core to a number of releases. Depending on the feature, this can range from a few months, to a few years (e.g. two years being about 100 releases of Jenkins and eight LTS baselines).

This deprecation policy needs to be supported by tools that check publicly accessible plugins for access to deprecated (or to-be-deprecated) APIs and generate reports on them to inform deprecation policy decisions.

Ideally, Jenkins core will be enhanced to include the capability to check both plugins for use of removed APIs, so it can refuse to load plugins considered incompatible with the running Jenkins version, and the update site generation should be improved to exclude plugins that are known incompatible with the core release downloading the plugin information.

Impact

The impact of this change is not currently known both due to the large number of deprecated APIs and because we don't currently have the tooling above.

Removal of APIs needs to be done carefully (rather than wholesale), and affected, open-source plugins hosted by the Jenkins project need to be fixed to no longer rely on those APIs. This will force users to update affected plugins when updating Jenkins itself (which may be inconvenient if the new plugin release not using deprecated APIs is not compatible with the previously installed version), but it should at least ensure continued operation of their plugins.

This change may increase the frequency by which new plugin versions require newer core releases to run, as the replacement APIs may be new to the release that deprecated the existing API.

Open questions

How long is the deprecation period before an API gets removed?
- Should the same duration be used for all deprecations, or should it depend on the specific API?
  - If the latter, what are the lower/upper bounds, if any, of the deprecation period before removal?
What steps need to be followed to define a removal date for an API? Examples:
1. Provide a list of affected plugins and propose how they can be fixed? (618 plugins are using a deprecated api among which a large number are only using Hudson.getInstance() or Plugin(), see details here. evernat)
2. Provide a list of affected plugins and fix them (possibly including releases)?
3. Public announcements of API removal?
4. Documentation (Javadoc) updates?
5. Add an annotation to the removed element to allow automated processing?
Who fixes the plugins?
- Have a team responsible for finding & fixing failures, if necessary incrementing the plugin’s baseline version to get access to the replacement?
Is it worth to automate the refactoring?
How to handle previously deprecated methods? (Especially if we plan to remove them all simultaneously)

Implementation work

Annotations for deprecated methods/classes/fields that indicate their expiration date/release in a standardized manner
plugin-compat-tester needs to be extended to determine use of deprecated, to-be-removed, and/or removed API?
Extend Jenkins itself to detect use of removed APIs in plugins while they're being loaded and don't load plugins that do that?
Extend update center generation to not provide plugins that are known to use APIs removed in the version the update center is generated for?
Idea: Introduce a facility to the Jenkins plugin/update system allowing us to declare that a specific version of the plugin is the first known to be compatible with a specific version of a (core or plugin) dependency. If you attempt to upgrade the dependency you will be blocked unless you also agree to update the dependent.

Participants

LTS team
possibly a new team? Core team?

References

https://groups.google.com/forum/#!msg/jenkinsci-dev/GRimfBRGrhY/9APHtWMICwAJ *Backward compatibility policy proposal wiki page

Remote link associated with this issue:
- deprecated-usage-in-plugins

danielbeck:

Original comment link

Raw content of original comment:

Related: https://wiki.jenkins-ci.org/display/JENKINS/Backward+compatibility+policy

danielbeck:

Original comment link

Raw content of original comment:

Filled the issue description with some (partly speculative) details.

Filled the issue description with some (partly speculative) details.

integer:

Original comment link

Raw content of original comment:

For me there is no difference whether i update plugins/core because of numerous bugs or because of API update/deprecate. So :+1: for any possible breakages for plugins, but only if they will lead for clean and good API.

For me there is no difference whether i update plugins/core because of numerous bugs or because of API update/deprecate. So 👍 for any possible breakages for plugins, but only if they will lead for clean and good API.

conficio:

Original comment link

Raw content of original comment:

May I suggest to tie the removal of API to the change of major versions. That way it clearly signals that such incompatibilities might happen, when upgrading major versions. It makes management so much easier, than having to check with every single LTS/or other release for potentially breaking API's/plugins.

So any major version change can remove API deprecated for more than 2 years. This should translate into the components (jars/maven dependencies) as well. And it is a policy that plugins that provide API can follow as well.

May I suggest to tie the removal of API to the change of major versions. That way it clearly signals that such incompatibilities might happen, when upgrading major versions. It makes management so much easier, than having to check with every single LTS/or other release for potentially breaking API's/plugins.

So any major version change can remove API deprecated for more than 2 years. This should translate into the components (jars/maven dependencies) as well. And it is a policy that plugins that provide API can follow as well.

danielbeck:

Original comment link

Raw content of original comment:

May I suggest to tie the removal of API to the change of major versions. That way it clearly signals that such incompatibilities might happen, when upgrading major versions. It makes management so much easier, than having to check with every single LTS/or other release for potentially breaking API's/plugins.

Jenkins does not have major version increases regularly (and I doubt we'll start introducing them now), so that may not be a viable solution.

To clarify, what you need is a clear indicator, before upgrading, independent of which version you're running, what the effects due to this policy will be? Both removed API (for your own Groovy scripts) and plugins known to be affected?

May I suggest to tie the removal of API to the change of major versions. That way it clearly signals that such incompatibilities might happen, when upgrading major versions. It makes management so much easier, than having to check with every single LTS/or other release for potentially breaking API's/plugins.

Jenkins does not have major version increases regularly (and I doubt we'll start introducing them now), so that may not be a viable solution.

To clarify, what you need is a clear indicator, before upgrading, independent of which version you're running, what the effects due to this policy will be? Both removed API (for your own Groovy scripts) and plugins known to be affected?

integer:

Original comment link

Raw content of original comment:

Good idea to start increasing major versions for real changes either it looks like project never changing anything. Major version is a clear indicator that you need carefully read changelogs and make some actions during update. I.e. minimal java version could be a major release.

Good idea to start increasing major versions for real changes either it looks like project never changing anything.
Major version is a clear indicator that you need carefully read changelogs and make some actions during update. I.e. minimal java version could be a major release.

lanwen:

Original comment link

Raw content of original comment:

Maybe switch to semver for regular releases instead of lts? major.minor.patch? And use major.minor.lts1, .lts2 for lts?

integer:

Original comment link

Raw content of original comment:

Semver doesn't fit into maven versioning well. I think the question will be to provide "vendor"-ing mechanism for jenkins builds as it something that CB do by introducing unknown version schemes. "vendoring" should also provide better anonymous statistics calculation.

batmat:

Original comment link

Raw content of original comment:

+1 for that one. I think this effort should certainly be tightly correlated to stephenconnolly's proposal* about finding maintainer-less plugins + the bit more recent adopt-a-plugin initiative.

https://groups.google.com/forum/#!topic/jenkinsci-dev/Ih0RviQ0G90

+1 for that one. I think this effort should certainly be tightly correlated to stephenconnolly's proposal* about finding maintainer-less plugins + the bit more recent adopt-a-plugin initiative.

https://groups.google.com/forum/#!topic/jenkinsci-dev/Ih0RviQ0G90

jglick:

Original comment link

Raw content of original comment:

Is it worth to automate the refactoring?

Perhaps org.netbeans.modules.jackpot30:jackpot30-maven-plugin could be used after some cleanup. We already have some refactorings for it to apply and it is not hard to add more.

Is it worth to automate the refactoring?

Perhaps org.netbeans.modules.jackpot30:jackpot30-maven-plugin could be used after some cleanup. We already have some refactorings for it to apply and it is not hard to add more.

evernat:

Original comment link

Raw content of original comment:

> Provide a list of affected plugins and propose how they can be fixed?

There are at least 618 plugins using a deprecated Jenkins api, among which a large number are only using Hudson.getInstance() or Plugin().
20 deprecated classes, 172 deprecated methods and 13 deprecated fields are used in plugins.
28 deprecated and public Jenkins classes, 318 deprecated methods, 58 deprecated fields are not used in the latest published plugins (and which may be removed as part of Jenkins 2.0 ?).
You can see details for each plugin and of used or not deprecated api at https://ci.jenkins-ci.org/view/All/job/Reporting/job/infra_deprecated-usage-in-plugins/lastSuccessfulBuild/artifact/target/output.html

Perhaps, some PR could be submitted to fix some of these plugins during Jenkins Hacksgiving in the next few days ?

> Provide a list of affected plugins and propose how they can be fixed?

There are at least 618 plugins using a deprecated Jenkins api, among which a large number are only using Hudson.getInstance() or Plugin().
20 deprecated classes, 172 deprecated methods and 13 deprecated fields are used in plugins.
28 deprecated and public Jenkins classes, 318 deprecated methods, 58 deprecated fields are not used in the latest published plugins (and which may be removed as part of Jenkins 2.0 ?).
You can see details for each plugin and of used or not deprecated api at https://ci.jenkins-ci.org/view/All/job/Reporting/job/infra_deprecated-usage-in-plugins/lastSuccessfulBuild/artifact/target/output.html

Perhaps, some PR could be submitted to fix some of these plugins during Jenkins Hacksgiving in the next few days ?

danielbeck:

Original comment link

Raw content of original comment:

evernat That's really cool, thanks! I set it up on https://ci.jenkins-ci.org/view/Infrastructure/job/infra_deprecated-usage-in-plugins

Two suggestions that would make this tool even better IMO:

A list of plugins by deprecated API would be useful, to inform API removal decisions ("What plugins need to be fixed to get rid of this thing?"). I expect this to be the more common use case rather than sweeping cleanup plugin by plugin, especially in the case of APIs deprecated through the introduction on an alternative, so you may not be able to clean them up without increasing the required Jenkins version a lot.
A list of APIs to be considered deprecated in addition to what's actually deprecated (to inform deprecation decisions). Alternatively, allow overriding the war file source so I can pass the path to a local file as argument.

evernat That's really cool, thanks! I set it up on https://ci.jenkins-ci.org/view/Infrastructure/job/infra_deprecated-usage-in-plugins

Two suggestions that would make this tool even better IMO:

A list of plugins by deprecated API would be useful, to inform API removal decisions ("What plugins need to be fixed to get rid of this thing?"). I expect this to be the more common use case rather than sweeping cleanup plugin by plugin, especially in the case of APIs deprecated through the introduction on an alternative, so you may not be able to clean them up without increasing the required Jenkins version a lot.
A list of APIs to be considered deprecated in addition to what's actually deprecated (to inform deprecation decisions). Alternatively, allow overriding the war file source so I can pass the path to a local file as argument.

jglick:

Original comment link

Raw content of original comment:

A list of plugins by deprecated API would be useful

Yes, this is crucial.

A list of APIs to be considered deprecated

Do we really need that? If you have a solid reason to deprecate something, IMO just do it. The tool output can be used to decide if and when to delete the deprecated API.

That said, getting Sorcerer up and running with all of @jenkinsci as input would be awesome. Then there would be no need to speculate. You could just select the API of interest and immediately see a list of usages. (GitHub text searches are instant and accomplish this for members with distinctive names, but not for methods with names like setEnabled or whatever.)

A list of plugins by deprecated API would be useful

Yes, this is crucial.

A list of APIs to be considered deprecated

Do we really need that? If you have a solid reason to deprecate something, IMO just do it. The tool output can be used to decide if and when to delete the deprecated API.

That said, getting Sorcerer up and running with all of @jenkinsci as input would be awesome. Then there would be no need to speculate. You could just select the API of interest and immediately see a list of usages. (GitHub text searches are instant and accomplish this for members with distinctive names, but not for methods with names like setEnabled or whatever.)

daspilker:

Original comment link

Raw content of original comment:

The infra_deprecated-usage-in-plugins job lists false positives. E.g. for the job-dsl-plugin it shows:

deprecated api used in plugin job-dsl-1.40 :
   classes : [hudson.model.Hudson$CloudList]

There is no direct usage of hudson.model.Hudson$CloudList. I only found one indirect usage through a field: https://github.com/jenkinsci/job-dsl-plugin/blob/job-dsl-1.40/job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/JenkinsJobManagement.java#L359. And that is not a deprecated API usage, nothing will break if hudson.model.Hudson$CloudList is replaced by jenkins.model.Jenkins$CloudList.

The infra_deprecated-usage-in-plugins job lists false positives. E.g. for the job-dsl-plugin it shows:

deprecated api used in plugin job-dsl-1.40 :
   classes : [hudson.model.Hudson$CloudList]

There is no direct usage of hudson.model.Hudson$CloudList. I only found one indirect usage through a field: https://github.com/jenkinsci/job-dsl-plugin/blob/job-dsl-1.40/job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/JenkinsJobManagement.java#L359. And that is not a deprecated API usage, nothing will break if hudson.model.Hudson$CloudList is replaced by jenkins.model.Jenkins$CloudList.

evernat:

Original comment link

Raw content of original comment:

daspilker I suggest that you create an issue at https://github.com/evernat/deprecated-usage-in-plugins/issues to continue the discussion and not in this page. (The answer could be yes and no, it depends on the point of view on source or on class.)

evernat:

Original comment link

Raw content of original comment:

daspilker, I have created this issue for you with an answer. In short, for (Cloud cloud : jenkins.clouds will not be displayed as using a deprecated api anymore. And I have added a list of deprecated api by plugins.

danielbeck, can you schedule the job periodically or at least run it once. Thanks.

daspilker, I have created this issue for you with an answer. In short, for (Cloud cloud : jenkins.clouds will not be displayed as using a deprecated api anymore.
And I have added a list of deprecated api by plugins.

danielbeck, can you schedule the job periodically or at least run it once. Thanks.

danielbeck:

Original comment link

Raw content of original comment:

evernat Very cool new list of plugins by deprecated API, thank you!

Would it make sense to ignore python-wrapper for this, or consider it in a category of its own? It looks like it uses everything because it's weird. (A similar problem with https://wiki.jenkins-ci.org/display/JENKINS/Extension+points with the plugin implementing all the extension points…)

I changed the job to run daily.

evernat Very cool new list of plugins by deprecated API, thank you!

Would it make sense to ignore python-wrapper for this, or consider it in a category of its own? It looks like it uses everything because it's weird. (A similar problem with https://wiki.jenkins-ci.org/display/JENKINS/Extension+points with the plugin implementing all the extension points…)

I changed the job to run daily.

evernat:

Original comment link

Raw content of original comment:

danielbeck, the python-wrapper plugin is now ignored. In fact, the job is currently scheduled hourly not daily. And you may discard old builds of the job.

danielbeck, the python-wrapper plugin is now ignored.
In fact, the job is currently scheduled hourly not daily. And you may discard old builds of the job.

danielbeck:

Original comment link

Raw content of original comment:

In fact, the job is currently scheduled hourly not daily.

Oops. Still, can't hurt.

And you may discard old builds of the job.

Done.

FWIW I think it would make sense to transfer the repo to jenkinsci/ or at least fork it there. evernat WDYT?

In fact, the job is currently scheduled hourly not daily.

Oops. Still, can't hurt.

And you may discard old builds of the job.

Done.

FWIW I think it would make sense to transfer the repo to jenkinsci/ or at least fork it there. evernat WDYT?

evernat:

Original comment link

Raw content of original comment:

Yes, no problem. You can fork it to jenkinsci/ My github id is evernat so that I can push to the repo.

Yes, no problem. You can fork it to jenkinsci/
My github id is evernat so that I can push to the repo.

danielbeck:

Original comment link

Raw content of original comment:

evernat Forked into jenkins-infra and made you external contributor. I changed the job to use that repo.

Navigation Menu

Repository navigation

[JENKINS-31035] Introduce a policy for API deprecation #21492

Problem definition

Proposal

Impact

Open questions

Implementation work

Participants

References

Problem definition

Proposal

Impact

Open questions

Implementation work

Participants

References

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[JENKINS-31035] Introduce a policy for API deprecation #21492

Description

Problem definition

Proposal

Impact

Open questions

Implementation work

Participants

References

Problem definition

Proposal

Impact

Open questions

Implementation work

Participants

References

Activity

jenkins-infra-bot commented on Oct 19, 2015

jenkins-infra-bot commented on Oct 20, 2015

jenkins-infra-bot commented on Oct 25, 2015

jenkins-infra-bot commented on Oct 26, 2015

jenkins-infra-bot commented on Oct 27, 2015

jenkins-infra-bot commented on Oct 27, 2015

jenkins-infra-bot commented on Oct 27, 2015

jenkins-infra-bot commented on Nov 5, 2015

jenkins-infra-bot commented on Nov 5, 2015

jenkins-infra-bot commented on Nov 5, 2015

jenkins-infra-bot commented on Nov 17, 2015

jenkins-infra-bot commented on Nov 18, 2015

jenkins-infra-bot commented on Nov 18, 2015

jenkins-infra-bot commented on Nov 18, 2015

jenkins-infra-bot commented on Nov 19, 2015

jenkins-infra-bot commented on Nov 19, 2015

jenkins-infra-bot commented on Nov 22, 2015

jenkins-infra-bot commented on Nov 22, 2015

jenkins-infra-bot commented on Nov 22, 2015

jenkins-infra-bot commented on Nov 22, 2015

jenkins-infra-bot commented on Nov 22, 2015

jenkins-infra-bot commented on Nov 26, 2015

jenkins-infra-bot commented on Mar 28, 2016

jenkins-infra-bot commented on Mar 28, 2016

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions