Skip to content

Docs: Clarify code coverage features and improve JaCoCo/Cobertura documentation

  • Start this issue's title with Docs: or Docs feedback:.

Problem to solve

Code coverage documentation is causing user confusion between two distinct features:

  • Coverage reporting (shows percentages in MR widget using coverage keyword)
  • Coverage visualization (shows line-by-line coverage in diffs using artifacts:reports:coverage_report)

Doc impact:

  • /ci/testing/code_coverage/ (main page)
  • /ci/testing/code_coverage/jacoco/
  • /ci/testing/code_coverage/cobertura/
  • /ci/yaml/artifacts_reports/ (coverage_report section)
  • /ci/yaml/ (YAML reference - coverage and artifacts:reports keywords)

Further details

User feedback:

  • Expect JaCoCo reports to show coverage percentages but only get line visualization
  • Page structure ("Coverage Reports" → "JaCoCo Coverage Reports") misleads users about feature purpose
  • Path matching failures with no actionable troubleshooting
  • Missing visual examples to understand what each feature does
  • artifacts:reports:coverage_report documentation contains key information about what the feature actually does
  • YAML reference documents coverage and artifacts:reports separately with no cross-referencing

Audience: Developers setting up CI/CD pipelines who need code coverage (Sasha, Software Developer persona)

Proposal

  1. Restructure main coverage page - Lead with clear distinction between the two features with visual examples
  2. Update artifacts reports page - Clarify coverage_report shows diff annotations, not percentages
  3. Improve troubleshooting - Practical guidance for path matching issues, especially for multi-module projects
  4. Add cross-references - Link between coverage keyword and coverage_report in YAML reference
  5. Clarify limitations upfront - Aggregated reports, file path requirements

🔗 Other links/references