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