This version of the SonarQube documentation is no longer maintained. It relates to a version of SonarQube that is not active.

See latest version
Start Free
10.0 | Project administration | Defining New Code

Was this page helpful?

Defining New Code

On this page

Defining what is considered new code is an important part of SonarQube's Clean as You Code approach to code quality and safety. By focusing on code that's been added or changed since your new code definition, you can set consistent quality requirements and expectations. Your new code will be issue free and you'll clean up the code you encounter along the way. For more information on new code and why it's important, check out Clean as You Code.

Setting your New Code definition

You can define new code at the global, project, or branch level.

  • Global level: Set a global new code definition at Administration > Configuration > General Settings > New Code. What you define as new code at the global level will be the default for your projects.
  • Project level: Set a new code definition for your project at Project Settings > New Code. What you define as new code at the project level will be the default for the project's branches if you're using an edition that supports multiple branches (starting in Developer Edition).
  • Branch level: You can define new code for each branch from the Actions column of the branches table on the project's New Code settings page if you're using an edition that supports multiple branches (starting in Developer Edition).

New code definitions

You can define new code as changes from a previous version, a specific analysis, a reference branch, or within a specific period (number of days):

  • Previous Version: Available at the global, project, and branch levels and works well for projects with regular versions or releases. Defines new code as any code that has changed code since the project's most recent version. The current version of a project is determined in different ways depending on the build system being used:
    • If the analysis is done using the SonarScanner for Maven, then SonarQube reads the version from the pom.xml file.
    • If the analysis is done with the SonarScanner for Gradle then SonarQube reads the version from the file.
    • In all other cases, the version must be explicitly specified by setting the analysis parameter sonar.projectVersion.
  • Number of days: Available at the global, project, and branch levels. Specify the number of days for a floating new code period. For example, setting the Number of Days to 30 creates a new code period beginning 30 days before the current date.
  • Specific analysis: Available at the branch level starting in Developer Edition and the project level for Community Edition. Choose a previous analysis as your new code definition. Any changes made since that analysis are considered New Code. Issues in new code are those that have appeared since a specific, defined version of the project. The version of a project is determined in the same way as for the previous version option, above. SonarQube defines the start date of the new code period as the date when the project was incremented to the specified version.
  • Reference Branch: Available at the project and branch levels. Choose a specific branch to define your new code. Any differences between your branch and the reference branch in the clone the scanner has access to at analysis time are considered new code. To avoid reference errors when cloning a repository, we recommend cloning all its branches.

    On the initial analysis of a branch, you can use a scanner parameter to specify a reference branch, overriding the server's new code definition. See the Analysis parameters page for more information about setting hierarchies and descriptions for various parameters.

When using any new code period type other than Reference Branch, we recommend completing your merges using the fast-forward option without a merge commit; examples include GitHub’s squash and merge or rebase and merge options. In this way, the blame for the merged commits will always have a more recent commit date.

How the new code definition affects your analysis results

During analysis of the main branch, what counts as a new code issue is determined by the following:

  1. SonarQube determines how your code is compared:
    • For the Reference branch option, the analyzed branch is compared to the current state of the reference branch based on SCM data obtained during analysis. If the SCM is not available, the two branches are compared based on their current state in SonarQube.
    • For the other options, SonarQube uses the start date of the new code period, calculated as follows:
      - Previous version: date when the project was first incremented to the version in question
      - Number of days: current date minus the specified number of days
      - Specific analysis: date of the past analysis that you select in the history. 
  2. All lines of code in all files under analysis that are not in the reference branch or have changed since the start date of the new code period are marked (and displayed in yellow in the SonarQube interface).
  3.  All issues with one or more of the marked lines as primary or secondary locations are categorized as new code issues.

The set of new code issues, in turn, affects many aspects of your results:

  • The default quality gate applies conditions only to new code issues.
  • New code metrics are separated from overall code metrics in the main branch overview and the overviews of the other branches.
  • The Measures panel separates new code data vs overall code data.
  • Selecting the Issues in new code filter found on the Your Project > Issues page allows you to quickly switch between issues in new code or issues in overall code.

The activity graphs separate activity in the new code from activity in the overall code.

© 2008-2024 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARLINT, SONARQUBE, SONARCLOUD, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License