1 year ago · ac01f973cc
--- a/server/sonar-docs/src/pages/instance-administration/quality-profiles.md
+++ b/server/sonar-docs/src/pages/instance-administration/quality-profiles.md
@@ -3,106 +3,167 @@ title: Quality Profiles
 url: /instance-administration/quality-profiles/
 ---

 **Quality Profiles** are a core component of SonarQube where you define sets of [**Rules**](/user-guide/rules/) that, when violated, raise issues on your codebase (example: Methods should not have a Cognitive Complexity higher than 15). Each individual language has its own Quality Profile.
 Quality profiles are a key part of your SonarQube configuration.
 They define the set of [rules](/user-guide/rules/) to be applied during code analysis.

 To manage Quality Profiles, navigate to the [**Quality Profiles**](/#sonarqube#/profiles) page. Here, you'll find the Quality Profiles grouped by language.
 Every project has a quality profile set for each supported language.
 When a project is analyzed, SonarQube determines which languages are used and uses the active quality profile for each of those languages in that specific project.

 Ideally, all of your projects will be measured with the same Quality Profile, but that isn't _always_ practical. For example, you might run into the following situations:
 Go to **Quality Profiles** to see all the currently defined profiles grouped by language.

 - You have different technical requirements from one project to another (for example, different rules might apply to a threaded/non-threaded Java application).
 - You want to ensure stronger requirements for some of your projects (for example, internal frameworks).

 You can define as many Quality Profiles as needed to fit your specific needs.
 ## Built-in and default profiles

 ## Default Quality Profiles
 SonarQube comes with a built-in quality profile defined for each supported language, called the **Sonar way** profile (it is marked with the **BUILT-IN** tag in the interface).
 The **Sonar way** activates a set of rules that should be applicable to most projects.

 Each language must have a default Quality Profile (marked with the Default tag). Projects that are not explicitly assigned to specific Quality Profiles are analyzed using the default Quality Profiles. There is also at least one built-in **Sonar way** Quality Profile for each language. SonarSource creates these Quality Profiles with rules that generally apply to most projects. 
 In a newly set up instance, the **Sonar way** profile is the default for every language (marked with the **DEFAULT** tag in the interface).
 The default profile is used for that language if no other profile is explicitly defined at the project level.
 The default profile for a given language can be changed.

 The **Sonar way** Quality Profiles are a good starting point as you begin analyzing code, and they start out as the default Quality Profiles for each language. However, we recommend that you **Copy** this profile (see **Copying a profile** below) and begin to fine-tune the rules. Why?

 - Default Quality Profiles are not editable, so you won't be able to customize the **Sonar way** to your needs.
 - The **Sonar way** becomes a baseline against which you can track your own Quality Profiles.
 - The **Sonar way** may be updated over time to adjust which rules are included and adjust rule severities.
 ## Customizing a quality profile

 ## Quality Profile permissions
 The **Sonar way** profile is designed to be broadly suitable for most projects, but it is intended only as a starting point.
 In most cases, you will want to adjust your profile as the project progresses.

 By default, only users with the global **Administer Quality Profiles** permission can edit Quality Profiles. This is set at **Administration > Security > Global Permissions**.
 If you have multiple projects, you might also need to have different profiles for each.
 You might run into the following situations

 SonarQube also allows users with the global **Administer Quality Profiles** permission to give an expert or group of experts permission to manage a specific Quality Profile. These experts only have permission for that Quality Profile, not all Quality Profiles. Grant permissions to specific Quality Profiles on the Quality Profile's page (**Quality Profiles > [Quality Profile name]**) under the **Permissions** heading by clicking the **Grant permissions to more users** button.
 * You have different technical requirements from one project to another.
 * You want to ensure stronger requirements for some of your projects than for others.

 ## Copying a Quality Profile
 Copying a profile works well when you need to make a few changes to a built-in profile. When you copy a profile, you start off with all of the activated rules from the profile you copied from. From here, you can activate or deactivate rules to fit your needs. After copying a profile, your new profile won't inherit any changes made to the original profile.
 New profiles can be created in two ways:

 Follow these steps to copy a profile: 
 1. Copying an existing profile and adjusting the copy.
 1. Extending an existing profile.

 1. Go to the Quality Profile page (**Quality Profiles > [ Profile Name ]**) of the profile you want to copy.
 1. Select **Copy** from the ![Settings drop-down](/images/gear.png) drop-down menu  in the upper-right corner of the page. 
 1. Give your new Quality Profile a name and click **Copy**

 ## Extending a Quality Profile
 Extending a profile works well when many or all of your projects follow a set of common rules, but some of your projects also need to follow additional rules. When you extend a profile, you create a child profile based on a parent profile. This child profile inherits all of the rule settings from the parent profile. If rules are activated or deactivated in the parent profile, they're activated or deactivated in the child profile. 
 ### Copying a quality profile

 While you can activate rules in your child profile that are deactivated in the parent profile, you cannot deactivate rules in the child profile that are active in the parent profile.
 When you copy a profile, you clone all activated rules of the original.
 From here, you independently activate or deactivate rules to fit your needs; your new profile won't inherit changes made to the original profile.

 Follow these steps to copy a profile

 1. Go to the page of the profile you want to copy (**Quality Profiles** > *profile name*).
 1. Select **Copy** from the ![Settings drop-down](/images/gear.png) menu in the upper-right corner of the page.
 1. Give your new profile a name and select **Copy**.
 1. Modify the copy as needed.


 ### Extending a quality profile

 When you extend a profile, you create a child profile that inherits all the _activated_ rules in the parent profile.
 You can then activate additional rules in the child, beyond those that are inherited.
 However, you cannot de-activate rules that are activated in the parent.
 In other words, extension works by adding rules to the child profile.

 Follow these steps to extend a profile:

 1. Create a base profile with your core set of rules by clicking the **Create** button on the **Quality Profiles** page, or use an existing profile as a base profile.
 1. From the **Quality Profiles** page (**Quality Profiles > [ Profile Name ]**), find your base profile in the list of Quality Profiles and select **Extend** from the ![Settings drop-down](/images/gear.png) drop-down menu.
 1. After giving your new profile a name, SonarQube opens your new profiles page. 
 1. Below the **Rules** table, click **Activate More** to add rules to your extended profile. 
 1. From the **Inheritance** table, you can see the hierarchy of inheritance for your profile, and you can change the parent profile by clicking the **Change Parent** button. 
 1. Create a base profile with your core set of rules by selecting the **Create** button on the Quality Profiles page, or use an existing profile as a base profile.
 1. Find your base profile (**Quality Profiles** > *profile name*) and select **Extend** from the  ![Settings drop-down](/images/gear.png) menu.
 1. After giving your new profile a name, SonarQube opens your new profile page.
 1. Below the **Rules** table, select **Activate More** to add rules to your extended profile.
 1. From the **Inheritance** table, you can see the hierarchy of inheritance for your profile, and you can change the parent profile by selecting **Change Parent**.

 Your new profile has all of the activated rules from the profile you copied, but you can activate or deactivate any rules from the **Rules** table by selecting the numbers in the **Active** and **Inactive** columns.


 ### Differences between copying and extending 

 The key differences between an extension of a profile and a copy are:

 * With an extension, you can only activate rules that are deactivated in the parent.
  With a copy, you can activate or de-activate any rules you like.
 * With an extension, any changes made to the parent will be automatically reflected in the child.
  This includes rules activated in the parent, rules deactivated in the parent, and new rules added to the parent by Sonar.
  With a copy, changes are not propagated because the copy is entirely independent.

 Copied profiles are typically used to establish a new common profile that you want full control over and that can serve as the base profile for all your projects.
 Extension is typically used to provide customized profiles for projects which all follow a common base set of rules, but where each also requires different additional ones.


 ## Quality profile permissions

 Your new profile has all of the activated rules from the profile you copied, but you can activate or deactivate any rules from the **Rules** table by clicking the numbers in the **Active** and **Inactive** columns. 
 By default, only users with the global **Administer Quality Profiles** permission can edit quality profiles.
 User permissions are defined at **Administration** > **Security** > **Global Permissions**.

 When you copy a profile, your new profile does not inherit any future rule updates made to the original profile. 
 SonarQube also allows users with the global **Administer Quality Profiles** permission to give an expert or group of experts permission to manage a specific profile.
 These experts only have permission for that specific profile.

 ## Comparing two Quality Profiles
 You can compare the activated rules between two Quality Profiles. This is especially useful when you're using a Quality Profile copied from another profile as you won't automatically inherit new rules added to the original Quality Profile. Comparing your custom Quality Profile to the original Quality Profile shows any additional activated rules that aren't in your Quality Profile.
 Permissions can be granted to manage specific quality profiles on that profile's page (**Quality Profiles** > *profile name*) under **Permissions** by selecting **Grant permissions to more users**.


 ## Comparing two quality profiles

 You can compare the activated rules between two quality profiles.
 This is especially useful when you're using a quality profile copied from another profile because you won't automatically inherit new rules added to the original quality profile.

 To compare two profiles:

 1. From the **Quality Profiles** page, click the name of the first Quality Profile you'd like to compare. 
 1. Select **Compare** from the ![Settings drop-down](/images/gear.png) drop-down menu. 
 1. Select the second Quality Profile you'd like to compare from the **Compare with** drop-down menu.
 1. From the **Quality Profiles** page, select the name of the first profile you'd like to compare.
 1. Select **Compare** from the ![Settings drop-down](/images/gear.png) menu.
 1. Select the second profile you'd like to compare from the **Compare with** drop-down menu.

 From here you can push rules between the two profiles using the ![Activate rule right](/images/activate_rule_compare1.png) buttons.


 ## Finding out what has changed in a quality profile

 From here you can activate rules between the two profiles using the ![Activate rule right](/images/activate_rule_compare1.png) buttons.
 When SonarQube notices that an analysis was performed with a quality profile that is different in some way from the previous analysis, a _quality profile event_ is added to the project's event log.
 To see the changes in a profile, navigate to the profile (**Quality Profiles** > *profile name*) and choose **Changelog**.
 This can help you understand how profile changes impact the issues raised in an analysis.

 ## Knowing what's changed in a Quality Profile
 When SonarQube notices that an analysis was performed with a Quality Profile that is different in some way from the previous analysis, a Quality Profile event is added to the project's event log. To see the changes in a profile, navigate to the profile (**Quality Profiles > [ Profile Name ]**) and choose **Changelog**. This may help you understand how profile changes impact the issues raised in an analysis.
 Additionally, users with the **Administer Quality Profile** privilege are notified by email each time a built-in profile is updated.
 These updates can be caused by updating SonarQube or updating third-party analyzers.

 Additionally, users with Quality Profile administration privileges are notified by email each time a built-in profile is updated. These updates can be caused by updating SonarQube or updating third-party analyzers.

 ## Using a Quality Profile on another SonarQube instance
 To use a profile from one SonarQube instance on another SonarQube instance, take the following steps:
 ## Importing a quality profile from another SonarQube instance

 1. From the source SonarQube instance, open the Quality Profile you want to use. 
 1. Select **Back up** from the ![Settings drop-down](/images/gear.png) drop-down menu. This exports the profile as an XML file.
 1. From the target SonarQube instance, click the **Restore** button on the **Quality Profiles** main page.
 1. Choose the XML file that you exported previously, and click **Restore**.
 To import a profile from another SonarQube instance, do the following:

 ## Using a non-default profile on a project
 One profile for each language is marked as the default profile. Barring any other intervention, all projects that use that language will be analyzed with that profile. To have a project analyzed by a non-default profile instead, start from **Quality Profiles**, and click through on your target profile, then use the Projects part of the interface to manage which projects are explicitly assigned to the profile.
 1. From the source SonarQube instance, open the quality profile you want to use.
 1. Select **Back up** from the ![Settings drop-down](/images/gear.png) menu.
   This exports the profile as an XML file.
 1. From the target SonarQube instance, select the **Restore** button on the **Quality Profiles** main page.
 1. Choose the XML file that you exported previously, and select **Restore**.

 ## Ensuring your Quality Profile has all relevant new rules

 Each time a new SonarQube version is released, new rules are added. New rules won't appear automatically in your profile, however, unless you're using a built-in profile or a profile extended from a built-in profile (see the **Extending a profile** section above).
 ## Applying profiles to projects

 If you're not using a built-in profile, you can compare your profile to the built-in profile to see what new on-by-default rules you're missing (see the **Comparing two Quality Profiles** section above).
 One profile for each language is marked as the default.
 Barring any other intervention, all projects that use that language will be analyzed with that profile.
 To have a project analyzed by a non-default profile instead, start from **Quality Profiles**, and navigate to your target profile, then use the **Projects** part of the interface to manage which projects are explicitly assigned to that profile.

 Another option is to go to the **Rules** page in SonarQube, and use the **Available Since** search facet to see what rules have been added to the platform since the day you upgraded.

 ## Ensuring your quality profile has all relevant new rules

 Each time a new SonarQube version is released, new rules are added.
 New rules won't appear automatically in your profile unless you're using a built-in profile or a profile extended from a built-in profile.

 If you're not using a built-in profile, you can compare your profile to the built-in profile to see which rules you're missing.

 Another option is to go to the **Rules** page in SonarQube and use the **Available Since** search facet to see what rules have been added to the platform since the day you upgraded.

 And finally, the **Quality Profiles** main page shows recently added rules in the **Recently Added Rules** section on the right side of the page.


 ## Avoiding deprecated rules

 The **Deprecated Rules** section of the **Rules** page is your first warning that a profile contains deprecated rules. This section with a pink background gives the total number of instances of deprecated rules that are currently active in profiles and a breakdown of deprecated rule count per profile. Clicking through here takes you to the **Rules** page to edit the profile in question.
 The **Deprecated Rules** section of the **Quality Profiles** page has a pink background and is your first warning that a profile contains deprecated rules.
 This section gives the total number of instances of deprecated rule(s) that are currently active in each Quality Profile, and provides a breakdown of deprecated rule(s) per profile.
 Selecting the **Deprecated Rules** section takes you either to the **Rules** page or to the relevant Quality Profile to investigate further.

 Alternatively, you can perform a **Rules** search for the rules in a profile and use the **Status** rule search facet (in the left sidebar) to narrow the list to the ones that need attention.

 Alternately, you can perform a **Rules** search for the rules in a profile (either manually or by clicking through from the **Quality Profiles** page) and use the **Status** rule search facet to narrow the list to the ones that need attention.

 ## Security

 The Quality Profiles service can be accessed by any user (even anonymous users). All users can view every aspect of a Quality Profile. That means anyone can see which rules are included in a profile, which rules have been left out, how a profile has changed over time, and compare the rules in any two profiles.
 The **Quality Profiles** page can be accessed by any user (even anonymous users).
 All users can view every aspect of any profile.
 That means anyone can see which rules are included in a profile, which rules have been left out, how a profile has changed over time, and compare the rules between any two profiles.

 To make rule profile changes (create, edit, or delete) users must be granted the **Administer Quality Profiles and Gates** permission.
 To create, edit, or delete a profile, a user must be granted the **Administer Quality Profiles** permission.

 A **project administrator** can choose which profiles their project is associated with. See Project Settings for more.
 A project administrator can choose which profiles their project is associated with.
--- a/server/sonar-docs/src/pages/user-guide/rules.md
+++ b/server/sonar-docs/src/pages/user-guide/rules.md
@@ -2,24 +2,30 @@
 title: Rules
 url: /user-guide/rules/
 ---
 ## Overview
 SonarQube executes rules on source code to generate issues. There are four types of rules:

 SonarQube evaluates your source code against its set of rules to generate issues.
 There are four types of rules:

 * Code Smell (Maintainability domain)
 * Bug (Reliability domain)
 * Vulnerability (Security domain)
 * Security Hotspot (Security domain)

 For Code Smells and Bugs, zero false-positives are expected. At least this is the target so that developers don't have to wonder if a fix is required.
 For Code Smells and Bugs, zero false-positives are expected. 
 At least this is the target so that developers don't have to wonder if a fix is required.

 For Vulnerabilities, the target is to have more than 80% of issues be true-positives.

 Security Hotspot rules draw attention to code that is security-sensitive. It is expected that more than 80% of the issues will be quickly resolved as "Reviewed" after review by a developer.
 Security Hotspot rules draw attention to code that is security-sensitive.
 It is expected that more than 80% of the issues will be quickly resolved as "Reviewed" after review by a developer.

 The Rules page is the entry point where you can discover all the existing rules or create new ones based on provided templates.


 ## Rules

 By default, when entering the top menu item "Rules", you will see all the available rules installed on your SonarQube instance. You have the ability to narrow the selection based on search criteria in the left pane:
 By default, when entering the top menu item "Rules", you will see all the available rules installed on your SonarQube instance.
 You have the ability to narrow the selection based on search criteria in the left pane:

 * **Language**: the language to which a rule applies.
 * **Type**: Bug, Vulnerability, Code Smell or Security Hotspot rules.
@@ -34,11 +40,14 @@ By default, when entering the top menu item "Rules", you will see all the availa
 * **Template**: display rule templates that allow to create custom rules (see later on this page).
 * **Quality Profile**: inclusion in or exclusion from a specific profile

 If a Quality Profile is selected, it is also possible to check for its active severity and whether it is inherited or not. See the Quality Profile documentation for more.
 If a Quality Profile is selected, it is also possible to check for its active severity and whether it is inherited or not.
 See [Quality Profiles](/instance-administration/quality-profiles/) for more information.


 ## Rule Details

 To see the details of a rule, either click on it, or use the right arrow key. Along with basic rule data, you'll also be able to see which, if any, profiles it's active in and how many open issues have been raised with it.
 To see the details of a rule, either click on it, or use the right arrow key.
 Along with basic rule data, you'll also be able to see which, if any, profiles it's active in and how many open issues have been raised with it.

 The following actions are available only if you have the right permissions ("Administer Quality Profiles and Gates"):

@@ -49,12 +58,12 @@ The following actions are available only if you have the right permissions ("Adm
  * You can extend rule descriptions to let users know how your organization is using a particular rule 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.

 <!-- sonarqube -->

 ## Rule Templates and Custom Rules

 Rule Templates are provided by plugins as a basis for users to define their own custom rules in {instance}. To find templates, select the **Show Templates Only** facet from the the "Template" dropdown:

 ![Rule templates.](/images/rule-templates.png)
 ![Rule templates](/images/rule-templates.png)

 To create a custom rule from a template click the **Create** button next to the "Custom Rules" heading and fill in the following information:
 * Name
@@ -68,7 +77,9 @@ You can navigate from a template to the details of custom rules defined from it

 ![Rule template details.](/images/rule-template-details.png)


 ### Custom Rules

 Custom Rules are considered like any other rule, except that you can edit or delete them:

 ![Custom rules.](/images/rules-custom.png)
@@ -78,7 +89,7 @@ Custom Rules are considered like any other rule, except that you can edit or del
 ## Extending Coding Rules

 Custom coding rules can be added. See [Adding Coding Rules](/extend/adding-coding-rules/) for detailed information and tutorials.
 <!-- /sonarqube -->


 ## Rule Types and Severities

@@ -101,7 +112,9 @@ If not...
 **Is the rule neither a Bug nor a Vulnerability?**  
 If so, then it's a Code Smell rule.


 ## How are severities assigned?

 To assign severity to a rule, we ask a further series of questions. The first one is basically:

 **What's the worst thing that could happen?**
@@ -117,25 +130,36 @@ Then we assess whether the impact and likelihood of the Worst Thing (see _How ar
 | Major    | ![](/images/cross.svg) | ![](/images/check.svg) |
 | Minor    | ![](/images/cross.svg) | ![](/images/cross.svg) |


 ## How are severity and likelihood decided?

 To assess the severity of a rule, we start from the Worst Thing (see _How are severities assigned?_, above) and ask category-specific questions.


 ### Bugs

 Impact: **Could the Worst Thing cause the application to crash or to corrupt stored data?**

 Likelihood: **What's the probability that the Worst Thing will happen?**


 ### Vulnerabilities

 Impact: **Could the exploitation of the Worst Thing result in significant damage to your assets or your users?**

 Likelihood: **What is the probability that an attacker will be able to exploit the Worst Thing?**


 ### Security Hotspots

 Security Hotspots are not assigned severities as it is unknown whether there is truly an underlying vulnerability until they are reviewed.


 ## What might change after a software update

 Sonar developers continually re-evaluate our rules to provide the best results. This process is evident in each release and means some rule-specific properties may change after an upgrade, even in a custom Quality Profile. This is normal and expected, and is no cause for alarm. The following are rule-specific properties that may change in an upgrade:
 Sonar developers continually re-evaluate our rules to provide the best results. As a result, the characteristics of some rules may change after an upgrade. This is normal and expected, and is no cause for alarm. 

 The following rule charactersitics that may change in an upgrade:

 - **Type:** Type (Bug, Vulnerability, Code Smell) updates happen on occasion. When a rule type is updated, its value will update automatically in every profile that uses it. Although the rule will be updated, issues previously raised by the rule will not be updated. For example, if a rule transitioned from Bug to Code Smell, the existing issues will retain their original Bug type, and new issues will get the new type, Code Smell.

@@ -145,4 +169,4 @@ Sonar developers continually re-evaluate our rules to provide the best results.

 - **Key:** Can change but this is uncommon. Typically this happens in the rare case that, for whatever reason, a key that was non-normal and needs to be normalized. When the key of a rule is changed, related issues are updated as well, so that they remain related to the re-keyed rule.

 - **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.
 - **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.