Deprecation policy

The goal of the deprecation policy is to ensure that users are aware of what is changing and have time to adjust before a feature or an API component is dropped on a 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, after the new LTA, with a minimum of 6 months after deprecation. For example, a feature deprecated in the 2025.2 version is kept until the 2026.1 LTA (Long-Term Active) version and dropped in the 2026.2 version or later. See Release cycle model for more information.

  • 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, but not before 6 months after 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.

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 Server (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 Monitoring 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 after the next LTA (Long-Term Active) release. See Release cycle model for more information.

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

PreviousDeprecationsNextMonitoring API deprecation

Last updated

Was this helpful?