Deprecating a Service-Lint Rule

This guide describes how to deprecate and eventually remove a rule. It is the companion to How to Add a New Rule.

When a rule is no longer supported or has been superseded, follow these steps rather than deleting it immediately, so users get advance notice.

1. Mark the Rule Class as Deprecated

Add the standard Java @Deprecated annotation to the rule class. This produces compile-time warnings for direct usages and signals that the rule is slated for removal.

@Deprecated
public class SomeOldRule extends AbstractRule {
    // ...
}

2. Update the @RuleDoc Annotation

Update @RuleDoc on the rule class to include deprecation metadata. This information drives the generated documentation and reports.

  • Set deprecated = true

  • Set deprecatedSince = "<version>" (e.g. deprecatedSince = "1.2.0")

@RuleDoc(
    id = "SL000",
    name = "Some Old Rule",
    // ...
    deprecated = true,
    deprecatedSince = "1.2.0"
)
@Deprecated
public class SomeOldRule extends AbstractRule {
    // ...
}

Removal Timeline

Rules typically remain in the codebase for two minor versions after deprecation:

  • Version N — rule is marked deprecated (e.g. 1.2.0).

  • Version N+1 — rule remains deprecated and functional.

  • Version N+2 — rule is eligible for removal (e.g. 1.4.0).

During this period the rule keeps executing unless explicitly disabled, but is clearly marked as deprecated in generated reports and documentation.

Cleanup (at the Removal Version)

  1. Delete the rule class and its associated tests.

  2. Remove references to the rule in DefaultRuleProvider (or equivalent registration) and the SPI file (META-INF/services/…​).

  3. Update any documentation or guides that referenced the rule, and remove its page from All Rules and nav.adoc.

See Also