New Code, Clean-as-You-Code, Baselines, and Legacy Modernization: Diagnostics, Failure Modes, and Production Practices

1. Diagnostics start with the failed evidence, not a new baseline

When a New Code gate surprises you, preserve the failing analysis before changing version, time window, reference, or specific-analysis key. The first job is to determine whether the failure came from source, scanner/SCM evidence, Compute Engine, quality policy, or the baseline itself.

2. Failure mode: reset the baseline after a red result

Suppose a project uses Previous version and fails on a new issue. The release owner changes sonar.projectVersion from 3.4.0 to 3.5.0 without fixing the issue, then reanalyzes. If the failing issue becomes part of overall code under the new period, the new-code gate can turn green even though the source defect remains.

Repair by restoring the approved version/baseline, preserving both analysis keys and gate results, fixing or explicitly governing the code risk, and recording the unauthorized policy change.

3. Failure mode: treating new code as only new files

A 2,000-line legacy file edited on ten lines can contribute those changed lines to New Code. Teams that mentally equate New Code with “files created after migration” will misread coverage and issue evidence. Inspect changed-line highlights, SCM blame, revision history, and the configured definition.

4. Failure mode: applying PR semantics to main-branch history

Pull-request analysis compares the PR’s changes to a target branch. Main-branch New Code may be based on version, time, a specific analysis, or another supported definition. Do not assume that “new” on main means “the diff from the previous commit.”

Current Community Build and commercial Server have different branch/PR capability envelopes. Record edition and analysis type before using PR observations to diagnose a main-branch period.

5. Failure mode: green New Code, ignored severe legacy risk

A green new-code gate is not a waiver for a critical inherited vulnerability, exposed secret, safety defect, or regulatory breach. New-code policy is one release control. Legacy security/reliability programs may require separate gates, manual controls, remediation deadlines, or emergency work.

6. Failure mode: comparing projects with different definitions

Project A uses 7 days, Project B uses Previous version with quarterly releases, and Project C uses a specific migration baseline. Their “new issues” and “new coverage” populations are not the same unit of measurement. Cross-project reporting must include definition metadata or normalize the comparison.

7. Failure mode: shallow SCM history harms New Code evidence

# Diagnostic only: prove whether the current repository is shallow.
git rev-parse --is-shallow-repository
git log --oneline --decorate -10

# In CI, prefer a full checkout. Example GitHub Actions concept:
# fetch-depth: 0

Do not “repair” a shallow-history warning by disabling SCM. Restore trustworthy history, then rerun the smallest equivalent analysis. Preserve the original scanner warning/log first.

8. Intentionally broken example: result-driven version bump

Run only against the disposable Chapter 12 project. Start from a known failing new-code state under Previous version, preserve report-task.txt, the version value, and gate response, then deliberately increment the version without changing source.

# Baseline evidence from the failed run
PRE_FAIL_SHA=$(git rev-parse HEAD)
cp .scannerwork/report-task.txt evidence/pre-bump-failure-task.txt

# Intentionally broken policy action: same source, new release boundary
sonar-scanner \
  -Dsonar.projectVersion="2.0.0" \
  -Dsonar.buildString="ch12-broken-version-bump"

POST_BUMP_SHA=$(git rev-parse HEAD)
test "$PRE_FAIL_SHA" = "$POST_BUMP_SHA"

If the New Code population or gate changes while SHA remains identical, you have proven that policy/version—not remediation—caused the signal change. Repair by returning to the approved baseline/version and addressing the source or using a formally approved risk decision.

9. Troubleshooting shortcuts to reject

• Do not change the window/reference/version until the failing evidence is preserved.
• Do not lower gate thresholds to match current metrics.
• Do not delete a project and recreate it with a new key to erase history.
• Do not disable SCM to silence blame or shallow-clone warnings.
• Do not mass-accept or suppress findings as a substitute for baseline governance.
• Do not directly edit SonarQube database/search state.
• Do not use an administrator token for routine scanning.

10. Production practices

1. Own New Code policy as configuration with named approvers.
2. Record definition/value next to every release-quality report.
3. Require full SCM history and stable version sourcing in CI.
4. Keep a separate severe-legacy-risk register even when the new-code gate is green.
5. Alert on unplanned baseline changes or project overrides when possible.
6. Review time windows periodically based on delivery cadence, not current gate results.
7. For upgrades, revalidate New Code semantics and APIs before assuming prior automation remains valid.

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.