SONAR-13787 Clarify the PR analysis process

diff --git a/server/sonar-docs/src/pages/analysis/jenkins.md b/server/sonar-docs/src/pages/analysis/jenkins.md
index 137781aa0ce7f2ca7b8d4e0451f6a2baebdaa2d2..7fd78f40f897ebebc220b9c053c1492cbcb0324a 100644 (file)
--- a/server/sonar-docs/src/pages/analysis/jenkins.md
+++ b/server/sonar-docs/src/pages/analysis/jenkins.md
@@ -79,6 +79,9 @@ Starting in [Developer Edition](https://redirect.sonarsource.com/editions/develo
 
 For configuration examples, see the [SonarScanner for Jenkins](/analysis/scan/sonarscanner-for-jenkins/) documentation.
 
+### Setting your Branch Source Plugin for Pull Request Decoration
+You need to configure your Multibranch Pipeline job correctly to avoid issues with Pull Request decoration. From your Multibranch Pipeline job in Jenkins, go to **Configure > Branch Sources > Behaviors > Discover pull requests from origin** and make sure **The current pull request revision** is selected.
+
 ## Detecting changed code in Pull Requests
 SonarScanners need access to a Pull Request's target branch to detect code changes in the Pull Request. If you're using a Jenkins Pull Request discovery strategy that only fetches the Pull Request and doesn't merge with the target branch, the target branch is not fetched and is not available in the local git clone for the scanner to read. 
 
@@ -93,3 +96,6 @@ To fix this, either change the discovery strategy or manually fetch the target b
 ```
 git fetch +refs/heads/${CHANGE_TARGET}:refs/remotes/origin/${CHANGE_TARGET}
 ```
+
+
+

diff --git a/server/sonar-docs/src/pages/analysis/pull-request.md b/server/sonar-docs/src/pages/analysis/pull-request.md
index cd4f237a7827287d275f6a74a43295b06e218c6a..5205ac7c080e3b47b7df16dc8ad839fb0cce6fee 100644 (file)
--- a/server/sonar-docs/src/pages/analysis/pull-request.md
+++ b/server/sonar-docs/src/pages/analysis/pull-request.md
@@ -5,12 +5,16 @@ url: /analysis/pull-request/
 
 _Pull Request analysis is available starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)._
 
-You can see your Pull Requests in SonarQube from the Branches and Pull Requests dropdown menu of your project.
+You can see your Pull Requests in SonarQube from the Branches and Pull Requests dropdown menu of your project.  
 
-Pull Request analysis allows you to see your Pull Request's Quality Gate and analysis in the SonarQube interface:
+Pull Request analysis shows your Pull Request's Quality Gate and analysis in the SonarQube interface. This analysis shows new issues introduced by the Pull Request before merging with the target branch:
 
 ![Pull Request Analysis.](/images/pranalysis.png)
 
+## Prerequisites
+
+Before analyzing your Pull Requests, make sure the Pull Request branch is checked out. Avoid any attempt at previewing the merge or actions involving your main branch.
+
 ## Pull Request Decoration
 You can also add Pull Request decoration that shows the Pull Request analysis and Quality Gate directly in your ALM's interface. See [Decorating Pull Requests](/analysis/pr-decoration/) for more information on setting it up.
 
@@ -33,4 +37,4 @@ The following parameters enable PR analysis.
 | --------------------- | ---------------------------------- |
 | `sonar.pullrequest.key` | Unique identifier of your Pull Request. Must correspond to the key of the Pull Request in your ALM.<br/> e.g.: `sonar.pullrequest.key=5` |
 | `sonar.pullrequest.branch` | The name of the branch that contains the changes to be merged.<br/> e.g.: `sonar.pullrequest.branch=feature/my-new-feature` |
-| `sonar.pullrequest.base` | The branch into which the Pull Request will be merged. <br/> Default: master <br/> e.g.: `sonar.pullrequest.base=master` |
+| `sonar.pullrequest.base` | The branch into which the Pull Request will be merged. <br/> Default: master <br/> e.g.: `sonar.pullrequest.base=master` |
\ No newline at end of file