9.8 | Project administration | Defining New Code

On this page

Defining New Code

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 gradle.build 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 changes made between your branch and the reference branch are considered New Code.
    You can also specify a reference branch using a scanner parameter, overriding the server's 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 calculates the start date of the new code period based on the new code option chosen.
    • In the case of the previous version option, this is the date when the project was first incremented to the version in question.
    • In the case of the number of days option, it is the current date minus the specified number of days.
    • In the case of the specific analysis, it is the date of the past analysis that you select in the history. 
  2. All lines of code in all files under analysis that 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.
  • The Issues page has a creation date facet where you can select to see only 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