API deprecation policy change

Hi all,

With the release of 9.3 we made an important change to our API deprecation policy that you should know about. The docs are updated to reflect the change, but we wanted to give plugin maintainers and web service consumers explicit notice here.

What changed?

Deprecated APIs are now only retained through one LTS release. Previously, they were kept for 2 LTSs.

Why did it change?

The old, 2-LTS policy was adopted when LTS cycles were much shorter. With the current ~18-month LTS cycle, keeping deprecated APIs for 2 cycles means supporting them for nearly 4 years. That’s a long time, and it was hindering our ability to innovate as quickly and as smoothly as we wanted to.

We also think this new policy is easier to understand because it moves us to semantic versioning, where major versions may not be not compatible with each other.

How does it work?

Everything deprecated during an LTS cycle will be kept until the next LTS is released. So anything deprecated in a 9.x version (9.0, 9.1, 9.2…) will be kept until 9.x LTS is released, and then dropped in 10.0.

What’s affected?

This applies to both Java APIs and Web APIs.

When is the change effective?

The change is effective immediately. So you should expect everything currently deprecated to be dropped in 10.0 as well as anything else that’s deprecated in future 9.x versions.

How will I know about new deprecations?

We’ll give notice of any new deprecations in the Upgrade Notes for the version, and of course they’ll also show up in the Jira Release Notes.

How often will you deprecate APIs?

We don’t deprecate APIs very often. When we do, our goal is to do it as early in an LTS cycle as possible, to give you as much notice as we can.

That doesn’t mean late-cycle deprecations won’t happen. But we do our best to avoid them.

Are there exceptions?

Yes, possibly. Under special circumstances, for example, when there are security vulnerabilities that need to be addressed, we will make an exception and drop the API early. But this should only happen in truly exceptional cases.

What should I do?

First and most importantly, as a plugin writer, plugin maintainer or consumer of Web APIs, you should not add new uses of deprecated APIs.

Second, you should make an assessment as soon as possible of whether you’re currently using any deprecated APIs. If you are, you should make the necessary updates in your next few releases so you’re ready for any breaking changes after the next LTS release.

Finally, you should keep an eye on the Upgrade Notes for new versions to stay up to date on any new deprecations.

I still have questions…

Please create new topics for questions & comments about this change, the deprecation policy, or APIs in general.

 
That’s all, folks!
:smiley:
Ann

7 Likes