Skip to content

ADR-0001-ci-badges.md

Latest commit

 

History

History
79 lines (56 loc) · 2.61 KB

ADR-0001-ci-badges.md

File metadata and controls

79 lines (56 loc) · 2.61 KB
Raw

ADR-0001: Use Shields.io Endpoint Badges

Status: Accepted Date: 2025-12-13

Context

We want to display dynamic code quality badges in the README that update automatically from CI runs. These badges should show:

  • Line coverage (JaCoCo)
  • Mutation score (PITest)
  • SpotBugs status

Options considered:

  1. Static badges - Manual updates required, always stale
  2. Codecov/SonarCloud - External services, require accounts and configuration
  3. Shields.io endpoint badges - Self-hosted JSON files, no external accounts needed

Decision

Use Shields.io endpoint badges that read from JSON files committed to the /ci/badges/ directory.

The CI workflow uses three jobs with artifact-based data transfer:

  1. build-test - Runs tests, JaCoCo, Checkstyle, SpotBugs on all pushes/PRs
    • Uploads test results and SpotBugs XML as artifacts
  2. mutation-test - Runs PITest mutation testing on 03 modules only (main branch only)
    • Uploads mutation results as artifacts
  3. update-badges - Runs after both jobs complete (main branch only)
    • Downloads artifacts from previous jobs
    • Python script (scripts/ci_metrics_summary.py) parses XML reports
    • Generates badge JSON files and commits with [skip ci]

Shields.io fetches JSON from raw.githubusercontent.com and renders the badge.

Badge JSON Format

{
  "schemaVersion": 1,
  "label": "coverage",
  "message": "85.2%",
  "color": "16A34A"
}

Badge URLs

[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jguida941/java-spring-tutorials/main/ci/badges/jacoco.json)]

Consequences

Benefits

  • No external dependencies - No accounts, API keys, or third-party services
  • Full control - We define colors, thresholds, and label text
  • Automatic updates - Badges update on every main branch push
  • Extensible - Easy to add new metrics (just add JSON file)

Drawbacks

  • Requires write access - CI needs permission to push to repo
  • Main branch only - Badges don't update from PR builds
  • Cache delay - GitHub raw content may be cached for a few minutes

Color Thresholds

Metric Green (90%+) Amber (75%+) Orange (60%+) Red (<60%)
Coverage 16A34A F59E0B EA580C DC2626
Mutation 16A34A F59E0B EA580C DC2626
SpotBugs 16A34A (0 issues) - - DC2626 (any issues)

References