Checkpoint Lab — Metrics: Reliability, Maintainability, Security, Complexity, and Size

1. Checkpoint scenario and success criteria

Use the Chapter 13 fixture—or an equivalent disposable project—to produce a metric interpretation dossier for two controlled revisions. Success is not “all metrics improve.” Success is proving what changed, why it changed, which signals did not change, what the values mean, and what they do not prove.

The dossier must distinguish source state, measurement inputs, server processing, metric definitions, policy context, and human interpretation.

2. Assumptions and preflight

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

3. Write predictions before the second revision

At minimum predict two state changes independently. A strong packet predicts several:

4. Execute the two-revision workflow

1. Run the baseline tests/coverage and commit the baseline.
2. Run baseline Sonar analysis and wait for CE success.
3. Discover available metric keys and capture baseline-metrics.json.
4. Pin the baseline analysis as the New Code reference using the Chapter 12 method.
5. Add the deliberately complex, untested routing function and commit once.
6. Regenerate coverage evidence without adding tests for the new function.
7. Run the second Sonar analysis and wait for CE success.
8. Capture change-metrics.json using the same helper and same metric-key discovery logic.
9. Do not modify profile, gate, scope, baseline, instance mode, or scanner/server versions between the two analyses.

5. Required evidence packet

evidence/
  assumptions.md
  instance-mode.txt
  server-version.txt
  scanner-version.txt
  python-tooling.txt
  baseline-revision.txt
  change-revision.txt
  baseline-coverage.xml
  change-coverage.xml
  baseline-report-task.txt
  change-report-task.txt
  baseline-ce-task.json
  change-ce-task.json
  metric-catalog.json
  baseline-metrics.json
  change-metrics.json
  metric-delta.txt
  new-code-definition.json
  project-profile-and-gate.md
  scope-and-indexing.md
  interpretation.md
  limitations.md
  recommendation.md
  cleanup.txt

Optional evidence includes screenshots, but the packet must remain interpretable without them. Do not store bearer tokens, passwords, cookies, or unrelated source.

6. Interpretation worksheet

7. Write a recommendation that uses multiple signals

A strong recommendation resembles:

Revision B added a new routing function that increased LOC and both structural complexity measures while decreasing New Code coverage. Reliability and security ratings did not degrade under the current MQR/Standard profile, which is consistent with the change being primarily structural. Maintainability issue/effort evidence should be reviewed at the rule level, but the letter rating alone is not sufficient to dismiss the complexity increase. Before merging a comparable production change, add focused tests for routing branches and consider refactoring the nested decision structure if the active rule/profile flags it or if change/test difficulty warrants it. No claim about runtime performance is supported by these metrics.

The recommendation uses source, complexity, coverage, ratings, and limitations together. It does not claim “score went down, therefore bad engineer.”

8. Mandatory limitations note

• Static analysis cannot prove runtime correctness or complete security.
• Rule/analyzer updates can change issue-derived metrics across time.
• Coverage depends on external test evidence and does not prove test quality.
• Complexity is language/analyzer-specific and is not runtime performance.
• LOC is scope/language-dependent and is not productivity.
• Debt effort is an estimate derived from rule remediation functions.
• New Code values depend on the recorded baseline/reference.
• Cross-project comparison requires a separate comparability contract.

9. Guarded cleanup and credential revocation

1. Copy evidence out of .scannerwork and verify both CE tasks are preserved.
2. Revoke the project-analysis token, Browse API token, and temporary project-admin token if created.
3. Delete the disposable project only after preserving the metric dossier and only if the key is uniquely the lab project.
4. Delete the local fixture/virtual environment when reproduction is no longer needed.
5. Do not delete shared SonarQube database/search state, global profiles/gates, unrelated projects, scanner caches, or infrastructure volumes as checkpoint cleanup.

10. What Chapter 13 adds to a governed SonarQube operating model

The organization can now state metrics as reproducible evidence: metric key, definition, population, source revision, mode/profile, analysis task, raw value, derived rating, trend window, and decision context. This prevents dashboards from becoming unexamined scoreboards and makes metric changes diagnosable.

Chapter 14—Coverage, Test Execution Data, Duplication, and External Analyzer Reports—takes four important evidence families that appeared here and teaches their import formats, provenance, path mapping, detection rules, and failure modes in depth.

Knowledge check

Official references and version notes

• Understanding measures and metrics — current metric definitions and metric keys for software qualities, maintainability, coverage, duplication, size, complexity, and issues.
• Code metrics introduction — how metrics participate in rules, quality gates, monitoring, and mode-dependent UI behavior.
• Changing instance modes — MQR versus Standard Experience classifications, severities, and metric-family implications.
• Instance mode overview — current MQR/Standard model and the default for new Community Build instances.
• Web API — bearer authentication, /api/measures, /api/metrics, and Web API V2 migration guidance.
• Understanding quality gates — how selected measures become enforceable policy rather than descriptive dashboards.
• New Code — population semantics used by new_* measures.
• Analysis overview — scanner/report/Compute Engine lifecycle behind persisted measures.
• Test coverage overview — current external-coverage model; Chapter 14 expands this subject.
• SonarQube downloads — current Community Build release identity.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the local lab.