Deprecation policy

The goal of the deprecation policy is to make sure that users are aware of what is changing and have time to adjust before a feature or an API component is dropped at a given planned date.

General principles

A backward-incompatible change or dropping of a public API endpoint, a workflow, or a feature is subject to the deprecation. Once deprecated, they will be removed in a future version:

• A deprecated feature can be dropped in the year following the year it was deprecated.

• See below for deprecated Web API or Plugin API components.

Web API deprecation policy

The Web API deprecation policy states that:

• An API component must be deprecated before being dropped. Furthermore, if the underlying feature is not being dropped, a replacement component must immediately be provided.

• A deprecated API component must be fully supported until its drop (For instance the implementation of a deprecated method can’t be replaced by throwing a new UnsupportedOperationException()).

• The API release cycle is tied to the Release cycle model.

• A deprecated API endpoint can be dropped in January of the year following the year it was deprecated.

Under special circumstances, for example, when there are security vulnerabilities that need to be addressed, we might make an exception and drop the deprecated API component earlier.

Plugin API deprecation policy

The Plugin API deprecation policy states that:

• An API component must be deprecated before being dropped. Furthermore, if the underlying feature is not being dropped, a replacement component must immediately be provided.

• A deprecated API component must be fully supported until its drop (For instance the implementation of a deprecated method can’t be replaced by throwing a new UnsupportedOperationException()).

• The API is released independently of SonarQube Community Build (see the version compatibility matrix).

• All breaking changes in the Plugin API must be preceded by a deprecation period of at least 2 years after the deprecation.

Under special circumstances, for example, when there are security vulnerabilities that need to be addressed, we might make an exception and drop the deprecated API component earlier.

Deprecation mark

A Plugin API component is marked as deprecated with both:

• The annotation @Deprecated.

• The Javadoc tag @deprecated whose message must start with "in x.y", for example:

* /**
 * @deprecated in 4.2. Replaced by {@link #newMethod()}.
 */
@Deprecated
public void foo() {
...
}

Policy recommendations for API users

• Regularly monitor the deprecation of API components and check if you’re currently using them. See API deprecation.

• If you’re currently using deprecated API components:

  • Don’t add new uses of it.

  • Make the necessary updates in your next few releases so you’re ready for any breaking changes.

Deprecation notice

Feature removals and deprecations are announced in the Release notes.

Plugin API deprecations are announced in the sonar-plugi-api GitHub repository.

Related pages

• Web API

• Plugin basics