The Quality Profiles service is the nervous center of Sonar. It enables to define the various sets of source code requirements that should be used when measuring the quality of projects. It also enables to define acceptable thresholds on measures and to trigger alerts when they are reached.A source code requirement is materialized by a coding rule in Sonar that is active, configured and has a severity. Here is an example: "A method central to SonarQube, since it is where you define your requirements by defining sets of rules (ex: Methods must not have a complexity greater than 10!". Out of the box, Sonar embarks for the Java language several coding rules (requirements) engines: Checkstyle, PMD and Findbugs. It also provides its own engine for advanced requirements. This represents more than 700 rules in total.
A quality profile is a set of source code requirements. Sonar enables to define several quality profiles to fit various types of projects. Indeed, the requirements are usually not the same when starting to develop from scratch an application or when maintaining an application which is 10 years old, when developing a technical library or a web application. A quality profile is also a set of visual alerts on measures. Here is an example of alert: "Highlight the complexity by method measure in the project's dashboard when its complexity by method is greater than 3."
Here is the entry page of the "Quality Profiles" service:
The Quality Profiles service can be accessed by any users (even anonymous users) but any changes (create, edit or delete) require to be logged in as a global administrator.
A project administrator can only change the quality profiles associated to its project(s). See Project Administration.
To create a quality profile, click on the Create button on the upper right and enter the name of the quality profile:
You can optionally provide some Checkstyle, PMD and Findbugs configuration files to fill the new quality profile with some existing rules configurations.
In order to copy an existing quality profile, click on the Copy button next to the profile you want to copy. You are prompted to give the name of the new profile. The profile is the exact copy of the copied one. You can then make desired changes to the new quality profile.
Click on the Rename button. You are prompted to give the new name of the profile.
Click on the Delete button. You are prompted to confirm the deletion.
Deleting a quality profile will delete the alerts defined in the profile and will remove the association with projects. If nothing else is done, Sonar will use the default profile to perform the next analysis on the (ex-)associated projects.
The rules configuration tab is the default page where you land when entering a profile. As there are numerous rules available, a very handy search engine is available in the rules configuration screen to filter only the ones to configure:
A rule can be activated or deactivated in a single click. Its severity and configuration in the profile can be changed as soon as it is activated.
Some "Bulk Change" actions are also available to quickly activate or deactivate a set of rules. For instance, you can easily add all Findbugs rules to an existing quality profile by: selecting this profile, searching for Findbugs rules and launching "Activate all" action:
No extra validation action is required to make changes to the profile.
Multiple Activations of a Rule
Some rules can be activated multiple times in the same quality profile with different parameters values. Checkstyle Regexp Singleline rule and PMD XPath rule are those kinds of rule.
If a rule can be activated multiple times, a Copy button is available at the end of the rule description:
Clicking on the Copy rule button displays a form to define the new rule from the parent one:
Once the new rule has been created, it can be managed as any other rules:
- the metric you are interested in
- whether the alert will be checked against the current value of the measure or the variation of this measure (available since Sonar 3.4)
- an operator (is greater than, is less than, etc.)
- the value that will trigger a warning
- the value that will trigger an error
Any changes will apply to the next analysis.
Maintaining Quality Profiles can be tedious over time, especially where there are many. To ease maintenance of profiles, Sonar provides the ability of inheriting from a profile. The principle is that for a custom profile, you can decide that it is going to have a parent profile by using the Profile Inheritance tab:
This means that the quality profile inherits all rules defined in the parent. This is shown visually in the rules configuration screen by a small blue marker next to the rule:
A rule inherited from a parent cannot be de-activated but it is possible to change its parameter(s) and / or its severity. As soon as one of those is changed, a red marker replaces the blue marker:
Changes made to an inherited rule can be reverted by using the button Revert to parent definition:
Alerts are not inherited from parent profiles.
Extending Rules Description
Each rule comes with a description in Sonar, but it sometimes needs to be extended: insufficient description, internal description, note on activation of a rule in a profile... This is why Sonar enables to extend rules description in two ways:
First the ability to extend the description of a rule to give more details for example. This is going to be attached to the rule in every profile and will also be available when clicking on a violation:
Image RemovedImage Removed
But we have also added the ability to comment a rule in the context of a specific quality profile, to comment for example why it has been assigned a high priority or a special threshold:
Associating Project to Quality Profile
To associate projects to a quality profile or to dissociate projects from a quality profile, go to the Projects tab:
This backup/restore mechanism is useful for instance to promote a quality profile from a test environment to a production environment or to share quality profiles with contractors.
Click on the Backup button to export an XML file.
To restore a quality profile, click on the Restore profile link on the upper right of the Quality profiles page, choose the XML file to restore and click on the Restore profile button: Image Removed
It is possible to compare 2 quality profiles to understand the differences between them:
The comparison service shows all differences (rules in one profile but not in the other, parameters differences) and also identical ones:
Every time a change is made to a quality profile, it is going to appear in the changes log:
See Extending Coding Rules for detailed information and tutorials.
Ideally, all projects will be measured with the same profile for any given language, but that's not always practical. For instance, you may find that:
- Technological implementation differs from one application to another (for example, different coding rules may apply when building threaded or non-threaded Java applications).
- You want to ensure stronger requirements on some of your applications (internal frameworks for example).
Which is why you can define as many quality profiles as you wish. To manage quality profiles, go to Quality Profiles (top bar), where you'll find profiles grouped by language. Here's an overview of this page:
As you can see above, language plugins always come with a predefined built-in profile (usually called "Sonar way") so that you can get started very quickly with SonarQube analyses. This is why as soon as you install a new language plugin, at least one quality profile will be available for you.
Each language must have a default profile (marked with a green check). Projects that are not explicitly associated with a specific profile will be analyzed using the language's default profile.
The Quality Profiles service can be accessed by any user (even anonymous users). All users can view every aspect of a profile. That means that anyone can see which rules are included in a profile, and which ones have been left out, see how a profile has changed over time, and compare the rules in any two profiles.
To make rule profile changes (create, edit or delete) users must be granted the Administer Quality Profiles and Gates permission.
A project administrator can choose which profiles his project is associated with. See Project Administration for more.