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 SonarQube Community Build release cycle.
- 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
@deprecatedwhose 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 the deprecated API components.
- 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 SonarQube Community Build release notes.
Plugin API deprecations are announced in the sonar-plugi-api GitHub repository.
Related pages
Was this page helpful?
© 2008-2025 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARQUBE, and CLEAN AS YOU CODE are trademarks of SonarSource SA.
