In SonarQube, plugins contribute rules which are executed on source code and which generate issues - that are used to compute technical debt. The Rules page is the entry point where you can discover all the existing rules or create new ones based on provided templates.
Click on the top "Rules" menu item to enter the world of rules. By default, you will see all the available rules in the following interface:
The search form always offers the following criteria:
- Available Since: date when a rule was first added on the SonarQube instance. This is useful to list all the new rules since the last upgrade of a plugin for instance.
- Characteristic: the SQALE characteristic to which a rule belongs (see Technical Debt).
- Language: the language to which a rule applies. Use "None" to find Manual Rules.
- Repository: the engine that contributes rules to SonarQube.
- Severity: the original severity of the rule - as defined by the plugin that contributes this rule.
- Status: rules can have 3 different statuses:
- Beta: The rule has been recently implemented and we haven't gotten enough feedback from users yet, so there may be false positives or false negatives.
- Deprecated: The rule should no longer be used because a similar, but more powerful and accurate rule exists.
- Ready: The rule is ready to be used in production.
- Tag: since SonarQube 4.2, it is possible to add tags to rules in order to classify them and to help discover them more easily.
- Templates: display rule templates that allow to create custom rules (see later on this page).
If a quality profile is selected, it is also possible to check for the activation status of the rule, its active severity or if it is inherited or not. See the Quality Profile documentation to know more about this.
Rules are displayed in detail on the right panel fo the page:
The 2 following actions are available only if you have the right permissions ("Administer Quality Profiles and Gates"):
- Add/Remove Tags:
- It is possible to add existing tags on a rule, or to create new ones (just enter a new name while typing in the text field).
- Note that some rules have built-in tags that you cannot remove - they are provided by the plugins which contribute the rules.
- Extend Description:
- Extending rule descriptions is useful to let users know how your organization is using a particular rule for instance or to give more insight on a rule.
- Note that the extension will be available to non-admin users as a normal part of the rule details.
Rule Templates and Custom Rules
Rule Templates are provided by plugins to allow users to define their own rules in SonarQube. For instance, the template "Architectural Constraint" (used in this page as an example) can be used to create any kind of rule that checks forbidden access from a set of file to another set of files.
In previous version of SonarQube, some rules (= the templates) could be "copied" to create new rules (= the custom rules), and it was possible to activate both the original rule and the new rules. That was misleading. SonarQube 4.4 makes it clear that:
- Rule Templates
- Can only be used to create custom rules
- Cannot be activated because they are just empty templates with empty parameters
- Custom Rules
- Are considered like any other rule
- But can be edited or deleted at any moment of time
It's easy to find rule templates that can be used to create new rules:
When creating a custom rule, you will have to fill the following information:
- Key (auto-suggested)
- Description (Markdown format is supported)
- Default Severity
- The parameters specified by the template
It's easy to navigate from a template to its custom rules: just click on the link in the "Custom Rules" section and you will end up on the details of the given rule.
Custom Rules are considered like any other rule, except that they can be fully edited or even deleted:
Note that when deleting a custom rule, it is not physically removed from the SonarQube instance but rather its status is set to "REMOVED". This allows current or old issues related to this rule to be displayed properly in SonarQube until they are fully removed.
Extending Coding Rules
Custom coding rules can be added. See Extending Coding Rules for detailed information and tutorials.