From: G. Ann Campbell Date: Tue, 26 Jun 2018 15:14:10 +0000 (+0200) Subject: add PR, 'generic' docs and general data re analysis X-Git-Tag: 7.5~918 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=7d56d0b2b288182336aca1931c5141684e6d57db;p=sonarqube.git add PR, 'generic' docs and general data re analysis --- diff --git a/server/sonar-docs/src/images/backgroundTaskProcessingFailedIcon.jpeg b/server/sonar-docs/src/images/backgroundTaskProcessingFailedIcon.jpeg new file mode 100644 index 00000000000..5b8bdc7e8a9 Binary files /dev/null and b/server/sonar-docs/src/images/backgroundTaskProcessingFailedIcon.jpeg differ diff --git a/server/sonar-docs/src/images/backgroundTaskProcessingInProgress.jpeg b/server/sonar-docs/src/images/backgroundTaskProcessingInProgress.jpeg new file mode 100644 index 00000000000..cf48fdab57b Binary files /dev/null and b/server/sonar-docs/src/images/backgroundTaskProcessingInProgress.jpeg differ diff --git a/server/sonar-docs/src/pages/analysis/generic_issue.md b/server/sonar-docs/src/pages/analysis/generic_issue.md new file mode 100644 index 00000000000..33c3ff456f6 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/generic_issue.md @@ -0,0 +1,84 @@ +--- +title: Generic Issue Data +--- + +SonarQube supports a generic import format for raising "external" issues in code. It is intended to allow you to import the issues from your favorite linter even if no plugin exists for it. + +External issues suffer from two important limitations: + +* they cannot be managed within SonarQube; for instance, there is no ability to mark them False Positive. +* the activation of the rules that raise these issues cannot be managed within SonarQube. In fact, external rules are not visible in the Rules page or reflected in any Quality Profile. + +External issues and the rules that raise them must be managed in the configuration of your linter. + +## Import +The analysis parameter `sonar.externalIssuesReportPaths` accepts a comma-delimited list of paths to reports. + +Each report must contain, at top-level, an array of `Issue` objects named `issues`. + +#### Issue fields: + +* `engineId` - string +* `ruleId` - string +* `primaryLocation` - Location object +* `type` - string. One of BUG, VULNERABILITY, CODE_SMELL +* `severity` - string. One of BLOCKER, CRITICAL, MAJOR, MINOR, INFO +* `effortMinutes` - integer, optional. Defaults to 0 +* `secondaryLocations` - array of Location objects, optional + +#### Location fields: + +* `message` - string +* `filePath` - string +* `textRange` - TextRange object, optional for secondary locations only + +#### TextRange fields: + +* `startLine` - integer. 1-indexed +* `endLine` - integer, optional. 1-indexed +* `startColumn` - integer, optional. 0-indexed +* `endColumn` - integer, optional. 0-indexed + +Here is an example of the expected format: + + { "issues": [ + { + "engineId": "test", + "ruleId": "rule1", + "severity":"BLOCKER", + "type":"CODE_SMELL", + "primaryLocation": { + "message": "fully-fleshed issue", + "filePath": "sources/A.java", + "textRange": { + "startLine": 30, + "endLine": 30, + "startColumn": 9, + "endColumn": 14 + } + }, + "effortMinutes": 90, + "secondaryLocations": [ + { + "message": "cross-file 2ndary location", + "filePath": "sources/B.java", + "textRange": { + "startLine": 10, + "endLine": 10, + "startColumn": 6, + "endColumn": 38 + } + } + ] + }, + { + "engineId": "test", + "ruleId": "rule2", + "severity": "INFO", + "type": "BUG", + "primaryLocation": { + "message": "minimal issue raised at file level", + "filePath": "sources/Measure.java" + } + } + ]} diff --git a/server/sonar-docs/src/pages/analysis/generic_test.md b/server/sonar-docs/src/pages/analysis/generic_test.md new file mode 100644 index 00000000000..47a5850076e --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/generic_test.md @@ -0,0 +1,96 @@ +--- +title: Generic Test Data +--- + +Out of the box, SonarQube supports generic formats for test coverage and test execution import. If your coverage engines' native output formats aren't supported by your language plugins, simply covert them to these formats. + +## Generic Coverage +Report paths should be passed in a comma-delimited list to: + + * `sonar.coverageReportPaths` + +The supported format is described by the `sonar-generic-coverage.xsd`: + + + + + + + + + + + + + + + + + + + + + + + + + + +and looks like this: + + + + + + + + + + + +The root node should be named `coverage`. Its version attribute should be set to `1`. + +Insert a `file` element for each file which can be covered by tests. Its `path` attribute can be either absolute or relative to the root of the module. +Inside a `file` element, insert a `lineToCover` for each line which can be covered by unit tests. It can have the following attributes: +* `lineNumber` (mandatory) +* `covered` (mandatory): boolean value indicating whether tests actually hit that line +* `branchesToCover` (optional): number of branches which can be covered +* `coveredBranches` (optional): number of branches which are actually covered by tests + +## Generic Execution +Report paths should be passed in a comma-delimited list to: + +* `sonar.testExecutionReportPaths` + +The supported format looks like this: + + + + + + other + + + stacktrace + + + stacktrace + + + + +The root node should be named `testExecutions`. Its version attribute should be set to `1`. + +Insert a `file` element for each test file. Its `path` attribute can be either absolute or relative to the root of the module. + +**Note** unlike for coverage reports, the files present in the report must be test file names, not source code files covered by tests. + +Inside a `file` element, insert a `testCase` for each test run by unit tests. It can have the following attributes/children: + +* `testCase` (mandatory) + * `name` (mandatory): name of the test case + * `duration` (mandatory): long value in milliseconds + + * `failure|error|skipped` (optional): if the test is not OK, report the cause with a message and a long description + * `message` (mandatory): short message describing the cause + * `stacktrace` (optional): long message containing details about `failure|error|skipped` status diff --git a/server/sonar-docs/src/pages/analysis/index.md b/server/sonar-docs/src/pages/analysis/index.md new file mode 100644 index 00000000000..8ddcdcd12d9 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/index.md @@ -0,0 +1,50 @@ +--- +title: Analyzing Source Code +--- + +Once the SonarQube platform has been installed, you're ready to install an analyzer and begin creating projects. To do that, you must install and configure the scanner that is most appropriate for your needs. Do you build with: + + +* TravisCI for SonarCloud - [SonarCloud Travis addon](https://docs.travis-ci.com/user/sonarcloud/) + +* Gradle - [SonarQube Scanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) +* MSBuild - [SonarQube Scanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) +* Maven - use the [SonarQube Scanner for Maven](https://redirect.sonarsource.com/doc/install-configure-scanner-maven.html) +* Jenkins - [SonarQube Scanner for Jenkins](https://redirect.sonarsource.com/plugins/jenkins.html) +* VSTS / TFS - [SonarQube Extension for VSTS-TFS](https://redirect.sonarsource.com/doc/install-configure-scanner-tfs-ts.html) +* Ant - [SonarQube Scanner for Ant](https://redirect.sonarsource.com/doc/install-configure-scanner-ant.html) +* anything else (CLI) - [SonarQube Scanner](https://redirect.sonarsource.com/doc/install-configure-scanner.html) + +**Note** that we do not recommend running an antivirus scanner on the machine where a SonarQube analysis runs, it could result in unpredictable behavior. + + +A project is created in the platform automatically on its first analysis. However, if you need to set some configuration on your project before its first analysis, you have the option of provisioning it via Administration options. + +## What does analysis produce? +SonarQube can perform analysis on 20+ different languages. The outcome of this analysis will be quality measures and issues (instances where coding rules were broken). However, what gets analyzed will vary depending on the language: + +* On all languages, "blame" data will automatically be imported from supported SCM providers. Git and SVN are supported automatically. Other providers require additional plugins. +* On all languages, a static analysis of source code is performed (Java files, COBOL programs, etc.) +* A static analysis of compiled code can be performed for certain languages (.class files in Java, .dll files in C#, etc.) +* A dynamic analysis of code can be performed on certain languages. + +## Will _all_ files be analyzed? +By default, only files that are recognized by a language analyzer are loaded into the project during analysis. For example if your SonarQube instance had only SonarJava SonarJS on board, all .java and .js files would be loaded, but .xml files would be ignored. However, it is possible to import all text files in a project by setting **Settings > Exclusions > Files > Import unknown files** to true. + +## What happens during analysis? +During analysis, data is requested from the server, the files provided to the analysis are analyzed, and the resulting data is sent back to the server at the end in the form of a report, which is then analyzed asynchronously server-side. + +Analysis reports are queued, and processed sequentially, so it is quite possible that for a brief period after your analysis log shows completion, the updated values are not visible in your SonarQube project. However, you will be able to tell what's going on because an icon will be added on the project homepage to the right of the project name. Mouse over it for more detail (and links if you're logged in with the proper permissions). + +![background task processing in progress.](/images/backgroundTaskProcessingInProgress.jpeg) + + +The icon goes away once processing is complete, but if analysis report processing fails for some reason, the icon changes: + +![background task processing failed.](/images/backgroundTaskProcessingFailedIcon.jpeg) + + +## F.A.Q. + +**Q.** Analysis errors out with `java.lang.OutOfMemoryError: GC overhead limit exceeded`. What do I do? +**A.** This means your project is too large or too intricate for the scanner to analyze with the default memory allocation. To fix this you'll want to allocate a larger heap (using `-Xmx[numeric value here]`) to the process running the analysis. Some CI engines may give you an input to specify the necessary values, for instance if you're using a Maven Build Step in a Jenkins job to run analysis. Otherwise, use Java Options to set a higher value. Note that details of setting Java Options are omitted here because they vary depending on the environment. diff --git a/server/sonar-docs/src/pages/analysis/scm_integration.md b/server/sonar-docs/src/pages/analysis/scm_integration.md new file mode 100644 index 00000000000..6f6c685cf84 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/scm_integration.md @@ -0,0 +1,18 @@ +--- +title: SCM Integration +--- + +Collecting SCM data during code analysis can unlock a number of SonarQube features: + +* Automatic Issue Assignment +* code annotation (blame data) in the Code Viewer +* SCM-driven detection of new code (to help with Fixing the Water Leak). Without SCM data, SonarQube determines new code using analysis dates (to timestamp modification of lines). + +### Turning it on/off +SCM integration requires support for your individual SCM provider. Git and SVN are supported by default. + +For other SCM providers, see the Marketplace. + + +Then, if need be, you can toggle it off at global/project level via administration settings. + diff --git a/server/sonar-docs/src/pages/branches/branches-faq.md b/server/sonar-docs/src/pages/branches/branches-faq.md index 58bacdcf22e..3460b07c8b9 100644 --- a/server/sonar-docs/src/pages/branches/branches-faq.md +++ b/server/sonar-docs/src/pages/branches/branches-faq.md @@ -1,5 +1,6 @@ --- title: Frequently Asked Branches Questions +order: 99 --- @@ -8,6 +9,7 @@ _Branch analysis is available as part of [Developer Edition](https://redirect.so + **Q:** How long are branches retained? **A:** Long-lived branches are retained until you delete them manually (**Administration > Branches**). Short-lived branches are deleted automatically after 30 days with no analysis. diff --git a/server/sonar-docs/src/pages/pull_request.md b/server/sonar-docs/src/pages/pull_request.md new file mode 100644 index 00000000000..7d3d447ca08 --- /dev/null +++ b/server/sonar-docs/src/pages/pull_request.md @@ -0,0 +1,64 @@ +--- +title: Pull Request analysis +--- + + + +_Pull Request analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)_ + + + + +Pull Request analysis allows you to: + +* see your Pull Request (PR) analysis results in the SonarQube UI and see the green or red status to highlight the existence of open issues. +* automatically decorate your PRs with SonarQube issues in your SCM provider's interface. + +PRs are visible in SonarQube from the "branches and pull requests" dropdown menu of your project. + +When PR decoration is enabled, SonarQube publishes the status of the analysis (Quality Gate) on the PR. + +When "Confirm", "Resolved as False Positive" or "Won't Fix" actions are performed on issues in SonarQube UI, the status of the PR is updated accordingly. This means, if you want to get a green status on the PR, you can either fix the issues for real or "Confirm", "Resolved as False Positive" or "Won't Fix" any remaining issues available on the PR. + +PR analyses on SonarQube are deleted automatically after 30 days with no analysis. This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. + +## Analysis Parameters +### Pull Request Analysis in SonarQube +These parameters enable PR analysis: + +| Parameter Name | Description | +| --------------------- | ------------------ | +| `sonar.pullrequest.branch` | The name of your PR
Ex: `sonar.pullrequest.branch=feature/my-new-feature`| +| `sonar.pullrequest.key` | Unique identifier of your PR. Must correspond to the key of the PR in GitHub or TFS.
E.G.: `sonar.pullrequest.key=5` | +| `sonar.pullrequest.base` | The long-lived branch into which the PR will be merged.
Default: master
E.G.: `sonar.pullrequest.base=master`| + +### Pull Request Decoration +To activate PR decoration, you need to: + +* declare an Authentication Token +* specify the Git provider +* feed some specific parameters (GitHub only) + +#### Authentication Token +The first thing to configure is the authentication token that will be used by SonarQube to decorate the PRs. This can be configured in **Administration > Pull Requests**. The field to configure depends on the provider. + +For GitHub Enterprise or GitHub.com, you need to configure the **Authentication token** field. For VSTS/TFS, it's the **Personal access token**. + +#### Pull Request Provider +| Parameter Name | Description | +| --------------------- | ------------------ | +| `sonar.pullrequest.provider` | `github` or `vsts`
This is the name of the system managing your PR. In VSTS/TFS, when the Analyzing with SonarQube Extension for VSTS-TFS is used, `sonar.pullrequest.provider` is automatically populated with "vsts". | + +#### GitHub Parameters +| Parameter Name | Description | +| --------------------- | ------------------ | +| `sonar.pullrequest.github.repository` | SLUG of the GitHub Repo | +| `sonar.pullrequest.github.endpoint` | The API url for your GitHub instance.
Ex.: `https://api.github.com/` or `https://github.company.com/api/v3/` | + +Note: if you were relying on the GitHub Plugin, its properties are no longer required and they must be removed from your configuration: `sonar.analysis.mode`, `sonar.github.repository`, `sonar.github.pullRequest`, `sonar.github.oauth`. + + +## TravisCI + GitHub.com + SonarCloud +All the analysis parameters are automatically populated if you are relying on the SonarCloud add-on. See https://blog.sonarsource.com/sonarcloud-loves-your-build-pipeline for more details. + +