Handling of deprecated rules

[guwirth (Günter Wirth)]

Hi,

like to mark a rule deprecated. Reading the javadocs this is done with the API deprecatedRuleKeys.

Rule Foo:A is defined in version 1 of the plugin
Rule’s key is renamed to Foo:B in version 2 of the plugin

 NewRepository newRepository = context.createRepository("Foo", "my_language");
 NewRule r = newRepository.createRule("A");
 ...
 NewRule r = newRepository.createRule("B")
   .addDeprecatedRuleKey("Foo", "A");

Question 1: If I’m using addDeprecatedRuleKey("Foo", "A") is it still necessary that the rule Foo:A exists in the repository?

Reading Rules, there is the status Deprecated.

Status: status does not affect the operation of a rule and has no impact on its issues. There are three possible rule statuses: beta, ready, and deprecated. Sometimes, rules are first issued in beta status and then moved to ready. Most rules are in ready status; ready to be used in production. When Sonar developers realize that a rule no longer makes sense, they first deprecate the rule, then eventually drop it.

Question 2: In case I keep the deprecated rule in the repository, is addDeprecatedRuleKey("Foo", "A") defining the status as Deprecated?

Question 3: In case of createRule("B").addDeprecatedRuleKey("Foo", "A"), is the API doing some automatic mapping from Foo:A to Foo:B or do I have to implement this in the plugin?

• Automatic mapping of existing Foo:A issues to Foo:B in the DB?
• What happens if there is a new deprecated Foo:A during analysis?

Thanks for your answer!

Regards,
Günter

[Colin]

Hey Gunter.

deprecatedRuleKeys isn’t for deprecating rules – it’s for deprecating rule keys (basically, if you want to change a rule key from language:MyRule to langauge:S1234, that’s when you would use this API).

If you just want to deprecate a rule, which means marking the status as deprecated (here’s an example comment in our sonar-java repo)

Now, if you are just trying to deprecate the key: no, you don’t need to keep a rule with the old key around as a standalone rule (and I doubt that would even work, although I’m not certain we’ve implemented logic to prevent this).

Keep in mind that deprecating a rule key only has one function: when you add a deprecated rule key to a rule, you are basically just making sure that when users restore Quality Profiles using the old key, it gets mapped to the new key. That’s it.

Edit: That last statement isn’t exactly true. See here.

Does that help?

[guwirth (Günter Wirth)]

Hello Collin,

thank you very much, that helps already …

deprecated rule status …

I understand: is an UI thing only …

addDeprecatedRuleKey … if you are just trying to deprecate the key: no, you don’t need to keep a rule with the old key around as a standalone rule …

Tried it with new AND deprecated key in repository.
I get the following during server start:

java.lang.IllegalStateException: The following rule keys are declared both as deprecated and used key [...]

Means I will remove the deprecated keys from the repository.

Keep in mind that deprecating a rule key only has one function: when you add a deprecated rule key to a rule, you are basically just making sure that when users restore Quality Profiles using the old key, it gets mapped to the new key. That’s it.

That’s the sentence I don’t understand: what does this “it gets mapped to the new key” mean?

1. In case there were Foo:A issues in V1 and I use addDeprecatedRuleKey to map it to Foo:B. All Foo:A in the DB are mapped to Foo:B?
2. In case I analyse in V2 and reporting an deprecated Foo:A key, is the scanner/SonarQube automatically mapping this to Foo:B key? Or do I have to handle this in my plugin?

Regards,
Günter

[Colin]

@guwirth

That’s the sentence I don’t understand: what does this “it gets mapped to the new key” mean?

It has nothing to do with analysis. It just means that if I have a Quality Profile XML backup with the old key, and I import that XML into a SonarQube instance that uses the new key, the Quality Profile will be able to know which rule is being referenced in the backup and should be activated.

Edit: This statement isn’t exactly true. See here.

[guwirth (Günter Wirth)]

Summary:

1. Rule status: status does not affect the operation of a rule and has no impact on its issues, essentially only the status is displayed in the Web UI. There are three possible rule statuses: beta, ready, and deprecated. Sometimes, rules are first issued in beta status and then moved to ready. Most rules are in ready status; ready to be used in production. When Sonar developers realize that a rule no longer makes sense, they first deprecate the rule, then eventually drop it.

Hint: Recommendation is to mark a rule first deprecated and remove/replace it in a later version then.

2. addDeprecatedRuleKey: If you want to rename the key of a rule or change its repository or both, register the rule’s previous repository and key This will allow SonarQube to support “issue re-keying” for this rule. If the repository and/or key of an existing rule is changed without declaring deprecated keys, existing issues for this rule, created under the rule’s previous repository and/or key, will be closed and new ones will be created under the issue’s new repository and/or key.

Hint: Rules marked deprecated with addDeprecatedRuleKey must no longer be in the repository, not even with the status deprecated. If this hint is ignored, the server start is aborted and the error message java.lang.IllegalStateException: The following rule keys are declared both as deprecated and used key ... is written to the LOG file.

3. If a sensor should support the old and new rule in a report during the analysis, the plugin must implement this itself.

• Mark rules as deprecated in the repository and no mapping in the sensor. Old rules/issues are displayed as deprecated.
• Remove deprecated rules in the repository and thus discard associated issues
• Remove deprecated rules in the repository and map to new rules in the plugin/sensor. Issues are all displayed under the new key.

[Colin]

Thanks Gunter. You made me realize I was wrong here:

@Colin

Keep in mind that deprecating a rule key only has one function: when you add a deprecated rule key to a rule, you are basically just making sure that when users restore Quality Profiles using the old key, it gets mapped to the new key. That’s it.

The second (maybe even primary) function of addDeprecatedRuleKey is as you said, that without marking the deprecated rule key,

existing issues for this rule, created under the rule’s previous repository and/or key, will be closed and new ones will be created under the issue’s new repository and/or key.

Sorry about that.