From 6d2119ef62e8c78488f2723dc56ad4fa69fec43f Mon Sep 17 00:00:00 2001 From: michaelbirnstiehl Date: Tue, 8 Jun 2021 10:12:26 -0500 Subject: [PATCH] SONAR-14131 Clarify quality profile extending --- .../src/images/activate_rule_compare1.png | Bin 0 -> 477 bytes server/sonar-docs/src/images/gear.png | Bin 0 -> 899 bytes .../quality-profiles.md | 105 +++++++++++------- 3 files changed, 65 insertions(+), 40 deletions(-) create mode 100644 server/sonar-docs/src/images/activate_rule_compare1.png create mode 100644 server/sonar-docs/src/images/gear.png diff --git a/server/sonar-docs/src/images/activate_rule_compare1.png b/server/sonar-docs/src/images/activate_rule_compare1.png new file mode 100644 index 0000000000000000000000000000000000000000..ce0d7cfebd7f604357c195bd8a01bc9cee01c198 GIT binary patch literal 477 zcmeAS@N?(olHy`uVBq!ia0vp^+(0bA!3HD`>}{K2=_l~cVkUtO*v#rA3CPe}WtdeCVW4?+SiY5n3^gK~f zOA literal 0 HcmV?d00001 diff --git a/server/sonar-docs/src/images/gear.png b/server/sonar-docs/src/images/gear.png new file mode 100644 index 0000000000000000000000000000000000000000..21d0c85a4204a044ec0067689c4d7653eff6f7be GIT binary patch literal 899 zcmeAS@N?(olHy`uVBq!ia0vp^%0Mj0!3HG5vqk>{Db50q$YKTtz9S&aI8~cZ8YswK z;_2(k{*+BfNLR}C`Mh;tA=ii!$I_CF{33>x>&|!pg?LJULN2Mr$wiq3C7Jno48oj> zAoICE;?DU6l|`B986^yB_|I4YMft#@MX8A(r3xjPxv31M-}yO#GMpfp;QX|b^2DN4 zhS-AtAm!X(!!wJMa}t3{ix{>a*wPOa<^TzYCl=*p=A|iB1I5@t%0eEamT(Rp@itjFX)iR1Nd zCeyb4G~9glX_slq5v^kfT+Mwi-O_7|5N~B^GFa-cse9e-cZ-sO*5vJyDoK>*P~(g= zUwDus=SZ4&%C*DC_^LV19A}xpcp&S_G@jsT?`9h23$$lH>F3(H{zm4tm0nGP zf0v0hv-z&AIqmu-i?wR&A{BuXFV3{_#g=tGvq}}cDjLMFs8gk}z-P<9kAC?FedYGl z94{);eZR{`YvJjn8(+?>{=Qj9XYGa!Ta>(V0!|c^ZC@B1#wfsX{6%4}fpjOg<+((D zHeX$}wUcZw#YWDym79O)`%mvUiP~D;Sh2%t=|;OZF5KOBd5f&AMpv)jxq_GfKF|5N zbC-z!x=WSW8tN1F?PDw7FFP}2((jDr+QKUFYbK-walWgwUfw4oaMb!tFB8X;o#~fM ztt^8>)<`IXpO>@(ik;}~7Gq?&#It8k%wc2MW707q?<9Y`oLRm1TGPCjn`f?At+RaH zra6<_rR%uAWh8ZN-oN0|SAW0YjY0>HOwKO3CwEA^D`#cLvaoaAuf@IE1S^jL`I0OO zJAOpDwkx`I=hYQU&!?UGb>d=`kI4JYGcyb`yxLAyX{>eAWj=7~mDTe; zb4CM;hvIVHp{1 Security > Global Permissions**. -By default, only users with the "Administer Quality Profiles" permission can edit Quality Profiles. But in large organizations, it may not be desirable to grant permissions to change all the Quality Profiles without distinction. That's why you can also grant users/groups the permission to edit an individual Quality Profile so that, for instance, the management of the Swift profile can be delegated to a group of Swift experts, and the same for COBOL, ... +SonarQube also lets you to grant permission to users or groups for specific Quality Profiles, so you can delegate profile management to a group of experts for that language. These users or groups only have permissions for that specific profile, not all Quality Profiles. -This delegation of permission can only be performed by someone who already has the "Administer Quality Profiles" permission or individual edit rights on the profile to which additional permissions should be granted. The interface to grant individual permissions is available on the profile detail page. +A user with the **Administer Quality Profiles** permission or individual edit rights for a specific Quality Profile can grant permissions on Quality Profile pages (**Quality Profiles > [ Profile Name ]**) under the **Permissions** heading. -### Copy the rules from one profile to another? +## 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. -Many times people want to work from a profile that's based on a built-in profile without actually using the built-in profile. The easiest thing to do in this case is to go to the original profile, we'll call it _Source_, in **Quality Profiles**. From there, click through on the total number of rules in _Source_ to land on the **Rules** page at a pre-narrowed search of _Source_'s rules. Use **Bulk Activate** to turn Source's rules on in your target profile. +Follow these steps to copy a profile: -### Know what's changed in a 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** -When {instance} notices that an analysis was performed with a 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. +## 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. -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. +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. + +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. -### Copy a profile from one SonarQube instance to another? +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. -Use the **Back up** feature on the source instance to export the profile to an XML file. Use the **Restore Profile** feature on the target instance to import the file. +When you copy a profile, your new profile does not inherit any future rule updates made to the original profile. -### Apply a core set of rules plus additional rules to a project? +## 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. -Let's say your company has a minimum set of coding rules that all teams must follow, but you want to add rules that are specific to the in use technology in your project. Those rules are good for your team, but irrelevant or even misleading for others. This situation calls for inheritance. Set up a base profile, we'll call it _Root_ with your core set of rules. Then create a child profile, we'll call it _Sprout_. Once it's created, you can **Change parent** to inherit from _Root_, then add your missing rules. +To compare two profiles: -Any profile that inherits from another Quality Profile will be updated when the parent Quality Profile is updated. +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. -### Make sure my non-default profile is used on a project? +From here you can activate rules between the two profiles using the ![Activate rule right](/images/activate_rule_compare1.png) buttons. + +## 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 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. -One profile for each language is marked 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 click through on your target profile, then use the Projects part of the interface to manage which projects are explicitly assigned to the profile. +## Using a Quality Profile on another SonarQube instance +To use a profile from one SonarQube instance on another SonarQube instance, take the following steps: -### Make sure I've got all the relevant new rules in my 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) 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**. -Each time a new SonarQube version is released, new rules are added, but they won't appear automatically in your profile unless you're using a built-in profile such as _Sonar way_. +## 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. -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. +## Ensuring your Quality Profile has all relevant new rules -Another option is to go to the **Rules** space, and use the **Available Since** search facet to see what rules have been added to the platform since the day you upgraded the relevant plugin. +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). -And finally, the profile interface itself will help you be aware of rules added in a new plugin version in the **Latest New Rules** section on the right of the interface. +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). -### Compare two profiles? +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. -Starting from the **Quality Profiles** page, click through on one of the profiles you'd like to compare, then use the **Actions > Compare** interface to select the second profile and see the differences. +And finally, the **Quality Profiles** main page shows recently added rules in the **Recently Added Rules** section on the right side of the page. -### Make sure I don't have any deprecated rules in my profile? +## Avoiding deprecated rules -The **Deprecated Rules** section of the rules interface itself is your first warning that a profile contains deprecated rules. This pink-background section gives the total number of instances of deprecated rules that are currently active in profiles, and a breakdown of deprecated count per profile. A click-through here takes you to the **Rules** page to edit the profile in question. +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. -Alternately, you can perform a **Rules** search for the rules in a profile (either manually or by clicking-through from **Quality Profiles** page) and use the **Status** rule search facet 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 profile. That means 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. +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. -To make rule profile changes (create, edit or delete) users must be granted the **Administer Quality Profiles and Gates** permission. +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 their project is associated with. See Project Settings for more. -- 2.39.5