New Code, Clean-as-You-Code, Baselines, and Legacy Modernization: Core Concepts and Mental Model

1. Current baseline and chapter boundary

Chapter 11 established that a quality gate evaluates a particular code population after Compute Engine finishes an analysis. Chapter 12 asks the next question: which lines and findings belong to the “new code” population? That answer is a policy decision expressed by the project’s New Code definition.

SonarQube Community Build separates overall code—the complete analyzed codebase—from new code, the recently added or modified portion selected by the configured definition. A healthy modernization program uses the strictest practical quality standard on new code while retaining visibility and separate ownership for inherited legacy risk.

2. Why legacy systems need a stable modernization boundary

A large inherited application may have years of low coverage, complex code, or unresolved issues. A big-bang policy that requires the entire codebase to meet a new standard before the next deployment can stop delivery without creating a feasible remediation path. The opposite extreme—ignoring all legacy debt—allows serious risk to persist indefinitely.

Clean-as-You-Code supplies a third operating model: prevent new debt and repair old code when you touch it, while governing the remaining legacy backlog separately. This makes improvement incremental, measurable, and compatible with normal product work. It does not mean old vulnerabilities, regulatory defects, or high-impact reliability risks can be forgotten.

3. Mental model: overall state plus a governed new-code lens

flowchart TD
O[Overall analyzed codebase] --> D[New Code definition]
R[Revision and SCM history] --> D
V[Version / analysis / time / reference] --> D
D --> N[New or modified code population]
P[Quality profile and rules] --> A[Analysis findings and measures]
N --> A
O --> A
A --> G[New-code quality gate]
G --> F[Modernization feedback]
L[Legacy-risk backlog] --> F
F --> C[Code fixes and governed future changes]

The overall codebase remains visible. The New Code definition applies a lens using version, time, a specific analysis, or a reference branch. Scanner/SCM evidence determines which lines are added or modified. The same rules analyze the code, but SonarQube reports separate new and overall measures so the gate can focus on recent changes while legacy work continues under its own risk plan.

4. Current New Code definition modes

Community Build’s current project documentation exposes configuration at global and project levels. A project-specific definition takes precedence over the inherited global baseline. The default global baseline is Previous version.

5. Previous version is a release concept, not “previous commit”

For Maven and Gradle, SonarQube can read the version from the build. With standalone Scanner CLI, set sonar.projectVersion explicitly. The Previous version definition uses the version boundary, not the immediately preceding Git commit. That distinction prevents a dangerous anti-pattern where every push would redefine new code and instantly make yesterday’s issue “old.”

6. SCM history is part of the measurement system

SonarQube uses SCM data for blame, issue dating/backdating, branch comparisons, and New Code detection. A shallow clone removes evidence needed to determine when lines changed. Current scanner guidance recommends full-depth checkout and warns that blame retrieval is skipped for shallow clones and analysis may fail.

Therefore a baseline dossier must record the commit SHA and checkout depth/SCM status—not only the UI setting. “Previous version, 30 days, or reference branch” is incomplete evidence when the scanner cannot see trustworthy history.

7. Read-only inspection before touching the baseline

export SONAR_HOST_URL="http://localhost:9000"
export PROJECT_KEY="academy-sq-ch12"

# Server identity
curl -fsS "$SONAR_HOST_URL/api/server/version"

# Current project-level/inherited New Code definition
curl -fsS -H "Authorization: Bearer $SONAR_ADMIN_TOKEN" --get \
  --data-urlencode "project=$PROJECT_KEY" \
  "$SONAR_HOST_URL/api/new_code_periods/show"

# Analysis history: revision, version, build string, analysis key
curl -fsS -H "Authorization: Bearer $SONAR_ADMIN_TOKEN" --get \
  --data-urlencode "project=$PROJECT_KEY" \
  --data-urlencode "ps=20" \
  "$SONAR_HOST_URL/api/project_analyses/search"

# New versus overall coverage evidence after analysis
curl -fsS -H "Authorization: Bearer $SONAR_ADMIN_TOKEN" --get \
  --data-urlencode "component=$PROJECT_KEY" \
  --data-urlencode "metricKeys=coverage,new_coverage,ncloc" \
  "$SONAR_HOST_URL/api/measures/component"

Use a browse-capable or project-admin lab credential only where required. Never print the token itself. The instance’s built-in Web API documentation is authoritative because endpoint surfaces are evolving.

8. DevOps control: baseline identity belongs beside revision identity

A reproducible quality signal must identify revision + effective analysis inputs + New Code definition/reference + Compute Engine task + gate definition/result. If a gate becomes green after only the baseline changed, that is a policy event—not a code fix.

For legacy modernization, report both new and overall measures. New-code success demonstrates that the team is not adding fresh debt. Overall trends and a separate risk backlog demonstrate whether inherited debt is actually shrinking.

Knowledge check

Official references and version notes

• Quality standards and new code — current New Code concepts, four definition modes, default baseline, and Clean-as-You-Code framing.
• Configuring new code calculation — project overrides, Specific analysis API-only behavior, and Previous version configuration.
• Global New Code baseline — global inheritance and the default Previous version baseline.
• Checked-out code — full Git history requirements for New Code, blame, and issue backdating.
• Issue management solution — issue identity/date/backdating and how current analysis relates findings to new code.
• Understanding quality gates — Sonar way and new-code-focused quality conditions.
• Feature comparison table — current Community Build versus Server/Cloud branch and pull-request boundaries.
• Analysis overview — scanner/report/Compute Engine processing and new/overall result computation.
• Web API — authenticated API usage and release-sensitive endpoint guidance.
• SonarQube downloads — current Community Build release identity.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the local lab.