Issue management solution

This document describes how SonarQube Server and its automated code review identify, assign, and synchronize issues. It also presents the issue's lifecycle and details issue-related features.

Issue identification and assignment by SonarQube Community Build

For each code file:

1. SonarQube Community Build checks if the file has been renamed.
2. SonarQube Community Build determines:

   • Whether an issue found during the current analysis is new or existed previously.
   • If an issue found during the previous analysis has been fixed.
3. For each new issue:

   • SonarQube Community Build determines and sets the issue date: the line’s last commit date when SCM data is available, or the analysis date otherwise. See Issue date and backdating for more information.
   • SonarQube Community Build tries to automatically assign the issue to an appropriate SonarQube Community Build user.

Method used to identify if an issue is new

SonarQube (Server, Cloud) use the same algorithm to determine whether an issue is new or existed previously:

• For each issue found in the file from the previous analysis, it compares it to each issue found in this file during the current analysis:

  • If there is no match then it considers the issue as Fixed.
  • If there is a match and the issue status is Fixed in the previous analysis then it reopens the issue.
• For each issue found in the file during the current analysis, if there is no matching issue in the file from the previous analysis then it is considered new.

This algorithm relies on the issue’s line hash. The line hash is calculated based on the content of the first line the issue is reported on, excluding the white spaces.

The figure below shows the comparison process between two issues.

• If the issue is on the same rule, with the same line hash (but not necessarily with the same message) : MATCH
• If the issue is on the same rule, on the same line number with the same message (but not necessarily with the same line hash): MATCH
• If the issue is on the same rule but the detected block moved inside the file, then if the issue is on the same line within the moved block, and has the same message: MATCH

Issue date and backdating

SonarQube Community Build determines an issue date for every new issue, that is, every issue that did not exist in the previous analysis. This date decides whether the issue is reported on new code or on old code (overall code). See Quality standards and new code for more information.

When SCM data is available for the line the issue is raised on, SonarQube Community Build always sets the issue date to that line’s last commit date, rather than to the analysis date. This requires SCM integration.

With the Previous version, Number of days, or Specific analysis option:

• If you changed the line, its commit date is recent, so the issue still counts as new code.
• If you did not change the line, its commit date predates the new code period, so the issue appears in overall code.

With the Reference branch option, new code is the set of differences between your branch and the reference branch, so an issue raised on a line you did not change is not on new code.

This keeps new code trustworthy: activating a rule or changing a rule parameter, a SonarQube Community Build update, a new analyzer version, or a change in the analysis context such as compiler, dependency, framework, or environment can still raise issues on untouched code, but those issues stay out of new code. See Understanding quality profiles for more information about activating rules and changing rule parameters.

For SonarQube Community Build to get reliable commit dates, we recommend a full-depth checkout of your repository. See Checked-out code for more information.

When no SCM data is available for the line, SonarQube Community Build uses the analysis date as the issue date. With the Previous version, Number of days, or Specific analysis option, that date falls inside your new code period, so the issue appears on new code.

During a pull request analysis, new issues on old code are not reported since only new code issues are reported. It means that the first analysis on the target branch after the merge may report new issues on old code that were not reported by the pull request analysis.

Automatic issue assignment

SonarQube Community Build automatically assigns an issue during analysis to the last committer on the issue line - called issue author - if the author can be correlated to a SonarQube Community Build user. Otherwise, it assigns the default assignee if a default assignee is configured in SonarQube Community Build.

Login and email correlations between the SCM account and the SonarQube Community Build user are made automatically. For example, if the user commits with their email address and that email address is part of their SonarQube Community Build user profile, then new issues raised on lines where the user was the last committer will be automatically assigned to the user.

• Currently, issues on any level above a file, for example, issues reported at a directory or project level, cannot be automatically assigned.
• If the SCM login associated with an issue is longer than 255 characters including the characters for an issue author, the author will be left blank.
• Several SCM accounts can be added to a SonarQube Community Build user account but the same SCM account should not be associated with several SonarQube Community Build accounts. See Associating with SCM account for more information.

Issue life cycle

An issue can have the following statuses:

• Open: initial value after the first analysis. A user can reopen an Accepted or False positive issue.
• Accepted: set by an authorized user if they decide to fix the issue later or not fix the issue. SonarQube Community Build ignores accepted issues in the ratings of the code but displays the number of accepted issues in the various analysis snapshots in the UI.
• False positive: set by an authorized user if the analysis is mistaken. SonarQube Community Build ignores False positive issues in the quality reports and ratings of the code.
• Fixed: set by SonarQube Community Build after a subsequent analysis if the previously open issue has been fixed in the code (is no longer being detected). By default, Fixed issues are purged after 30 days. This is set in Housekeeping.

If users tend to mark a lot of issues as False positive, it means that some coding rules are not appropriate for the project. In that case, rules can be deactivated in quality profiles, or the analysis scope of the project can be adjusted to exclude files. See Understanding quality profiles and Setting analysis scope for more information.

The figure below shows the issue life cycle.

Issue synchronization between branches

When you create a new branch, SonarQube Server transfers the attributes of the issues (status, assignee, changelog, comments) from the branch defined as "main" to the new branch. This way, if you had, for example, marked an issue in the main branch as False positive, this issue will still be marked as False positive in the new branch after its first analysis.

In order to use another reference branch, you can use the sonar.newCode.referenceBranch inAnalysis parameters when running the first analysis.

Issue synchronization applies also in case of a merge:

• With pull request: after the merge, SonarQube Community Build transfers the attributes of the issues from the pull request analysis to the target branch.
• Without pull request: if the New Code Definition of the branch to be merged is Reference branch, and the branch is merged into its reference branch, after the merge, SonarQube Community Build transfers the attributes of the issues from the branch analysis to the reference branch.

The figure below illustrates the issue synchronization between branches.