New code definition

Setting up the right New Code definition for your project is an important step in getting the most out of SonarCloud. When you do an analysis on your main branch (or other long-lived branches), SonarCloud uses the new code definition to determine which issues you should focus on fixing and highlights these as issues in new code. This helps you to use the Clean as You Code methodology to improve your code quality and code security in a manageable and efficient way.

Setting your new code definition

Setting your new code definition is a mandatory step when creating new projects on SonarCloud. During project creation, you will be taken to a screen where you must set the new code definition. If your organization already has an new code definition that is compliant with the Clean as You Code methodology, it will be proposed by default.  Otherwise, you have to select one.

After your initial new code definition selection, if necessary, you can later modify your new code definition at the organization level or project level:

• Organization level: Set a global new code definition for new projects at My Organization > Administration > New Code. What you define as new code at the organization level will then be used as the default setting for your new projects and only applies to new projects when they are first imported into the SonarCloud organization.
• Project level: Modify the new code definition for your existing project at My Organization > My Project > Administration > New Code. What you define as new code at the project level will supersede what was defined at the organization level.

New code definition options

You can define new code using one of these four definitions:

• Previous version: Recommended for projects with regular versions or releases. Defines new code as any code that has changed since the most recent version increment of the project. 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 SonarCloud reads the version from the pom.xml file.
  • If the analysis is done with the SonarScanner for Gradle then SonarCloud 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. Do not use your build number as sonar.projectVersion.

• Number of days: Recommended for projects following continuous delivery. Defines new code as any code that has changed in the last X days (max 90). For example, setting the Number of Days to 30 creates a new code period beginning 30 days before the current date. If no action is taken on a new issue after 30 days, this issue becomes part of the overall code.
• Specific version (Web API only): Defines new code as any code that has changed since a specific, defined version of the project. For more compliance with the Clean as You Code methodology, this option cannot be set in the UI, as it would require frequent user action to be kept up to date. 
• Specific date (Web API only): Defines new code as any code that has changed since a specific, defined date.

How the new code definition affects your analysis results

During analysis of the main branch or other long-lived branches what counts as a new code issue is determined as follows:

1. SonarCloud calculates the start date of the new code period based on the new code definition option chosen.
   • In the case of the previous version and specific version options, 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 date option, it is simply the specified date.
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 the code block is displayed in blue in the SonarCloud interface).
3. All issues with one or more of the marked lines as primary or secondary locations are categorized as new code issues.

For analysis of pull requests and short-lived branches, the new code definition is not used. Instead, the new code issues are those introduced by the pull request or short-lived branch itself. See the Pull request analysis and Branch analysis pages for details.

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 page separates the data reports into two lists to give a New Code vs Overall Code comparison.
• The Issues page has a Creation Date filter where you can select to see your Overall Code issues, or only issues found in in New Code.
• The Activity graphs separate activity in New Code from activity in Overall Code.

As an alternative to the UI, you can also use the Web API to set your new code definition. While choosing an option, you should take into account your development context. If you're importing several projects at once (bulk project import) using the Web API, knowing how the New Code definition options affect your analysis results can be helpful. 

Setting the new code definition using the API

To use the Web API to set your New Code definition, you need to use an alternative endpoint, POST api/settings/set:  https://sonarcloud.io/web_api/api/settings?query=settings&deprecated=false

New code definition - API calls 

To set your new code definition, you need to make two separate API calls. You can choose one of the four NCD options listed below