Checkpoint Lab — New Code, Clean-as-You-Code, Baselines, and Legacy Modernization

1. Checkpoint scenario

You own a deliberately imperfect legacy service. Your task is to demonstrate that a stable New Code policy can let new work meet a modern standard while legacy risk remains visible. Then you will alter only the baseline definition, prove the resulting measurement change, restore the approved baseline, and document why the greener-looking alternative is not automatically the better policy.

2. Resource and credential preflight

• □ Local SonarQube Community Build 26.9.0.129388 is healthy.
• □ SonarScanner CLI 8.1.0.6389 is recorded.
• □ Python 3.11+ and Git are recorded.
• □ The repository is full-depth and not shallow.
• □ academy-sq-ch12 is disposable and uniquely identified.
• □ Scanner uses a project-analysis token; policy mutation uses a separate temporary admin credential.
• □ No production source, user identity, database, CI provider, cluster, or credential is involved.

git rev-parse --is-shallow-repository
git rev-parse HEAD
sonar-scanner --version
python --version
curl -fsS "$SONAR_HOST_URL/api/server/version"

3. Write predictions before execution

4. Execute the controlled modernization workflow

Use the exact fixture and commands from Lesson 2 or reproduce an equivalent fixture whose legacy baseline is demonstrably imperfect and whose new slice is thoroughly tested. Keep these invariants:

1. Baseline analysis is identified by sonar.buildString and analysis key.
2. Specific analysis points to that exact approved baseline.
3. New source has enough coverable lines to avoid a trivial small-change interpretation.
4. The definition experiment reruns the same Git SHA.
5. The gate/profile/scanner/server stay fixed during the definition-only experiment.
6. The final state restores the Specific analysis baseline.

5. Build the evidence packet

evidence/
  assumptions.txt
  baseline-revision.txt
  baseline-coverage.xml
  baseline-report-task.txt
  project-analyses.json
  new-code-specific-baseline.json
  change-revision.txt
  change-coverage.xml
  change-report-task.txt
  measures-specific-baseline.json
  gate-specific-baseline.json
  definition-experiment-revision.txt
  new-code-one-day.json
  one-day-report-task.txt
  measures-one-day.json
  gate-one-day.json
  new-code-restored.json
  restored-report-task.txt
  measures-restored.json
  gate-restored.json
  scanner-versions.txt
  scm-state.txt
  baseline-change-control.md
  legacy-risk-note.md
  cleanup.txt

Do not store token values. If a raw log includes authorization material or local secrets, redact a copy while retaining the sensitive original only in an appropriately protected lab location—or avoid collecting that field entirely.

6. Verification checklist

• □ Baseline analysis key maps to the baseline revision/build string.
• □ Specific analysis definition references that key.
• □ Change revision differs from baseline revision.
• □ Overall coverage remains materially lower than new coverage under the approved baseline.
• □ Definition-only experiment uses exactly the same source SHA as the preceding run.
• □ One-day definition and restored definition responses are preserved.
• □ Every scanner run is correlated to a ceTaskId and CE completion.
• □ Gate results are recorded after CE completion, not inferred from scanner exit status.
• □ Full SCM state is proven.
• □ No source or policy was silently changed to force expected numbers.
• □ Final policy is the approved governed baseline.

7. Baseline-change control note

# New Code baseline change control
Project: academy-sq-ch12
Current approved definition: SPECIFIC_ANALYSIS
Approved analysis key / revision:
Experiment definition: NUMBER_OF_DAYS / 1
Source SHA during experiment:
Reason for experiment: demonstrate population sensitivity only
Observed impact on new-code measures/gate:
Impact on legacy-risk visibility:
Why experiment definition is or is not suitable for production:
Approver / owner:
Rollback: restore approved SPECIFIC_ANALYSIS key
Verification after rollback:
Review / expiry: immediate after lab

The note must explain the policy using delivery semantics, not “this setting is greener.”

8. Legacy-risk note

Record at least one inherited quality gap from the fixture—such as low overall coverage—and state what the new-code gate does and does not address. In a real system, this note would also list severe vulnerabilities, reliability defects, regulatory issues, ownership, target dates, and compensating controls.

9. Guarded cleanup and rollback

1. Confirm the approved New Code definition is restored.
2. Copy evidence outside .scannerwork.
3. Revoke the project-analysis token and temporary admin token; record the time.
4. Delete the disposable project only if it was created solely for the checkpoint and evidence is already preserved.
5. Delete the local fixture/virtual environment only when reproduction is no longer needed.
6. Do not delete SonarQube database/search state, Docker volumes, global caches, unrelated projects, or shared quality policy as cleanup.

10. What Chapter 12 adds to a governed production operating model

After this checkpoint, “new code” is no longer an unexplained dashboard filter. It is a versioned policy boundary linked to a definition/reference, revision/SCM state, analysis task, measures, gate results, and an explicit modernization strategy.

The organization can now say both: “we are not adding new debt” and “we still own this inherited debt.” Chapter 13—Metrics: Reliability, Maintainability, Security, Complexity, and Size—builds on that foundation by defining exactly what the resulting measures mean and where metric interpretation can go wrong.

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.