Draft: docs: badge unit and integration coverage, and say what the numbers mean
What
Add a pipeline-status badge and two coverage badges to the README, and correct the Coverage strategy section to match how coverage is actually computed.
Stacked on !1930.
Why: the badges
The README carried no badges at all. Each coverage badge reads a single job through the badge endpoint's job= parameter, which is what keeps them a unit-versus-integration split rather than one blended number:
| Badge | Endpoint | Reads |
|---|---|---|
| unit tests | coverage.svg?job=go_unittests |
66.80% |
| integration | coverage.svg?job=test:integration:+[POSTGRES,+18] |
91.40% |
Both verified against the live endpoint, along with key_text for the labels.
The default coverage.svg is deliberately not among them. GitLab computes it as the unweighted mean of every job carrying a coverage: regex, which on this branch is 19 of them. A three-package Redis leg weighs the same as the whole unit suite, and the PostgreSQL matrix enters the mean three times over. It is not the repository's statement coverage, and two pipelines' values are not comparable, because the changes: rules decide which jobs run and so which values are averaged.
Why: the doc correction
Coverage strategy said "Two CI jobs contribute to coverage" and "The pipeline badge averages the two job-level percentages". Both were true when written.
This MR keeps the table and the mean/shard/merge reasoning that !1781 adds, and layers on top:
- The count: nine definitions carry a
coverage:regex, expanding to 19 concrete jobs on the default branch. Derived from the YAML on this branch rather than copied, since matrix legs inherited throughextendsare easy to miss. - Two properties of the mean that invite a wrong reading: it is not statement coverage, and it is not comparable across pipelines.
- What the badges measure, and the fact that the integration badge names one matrix leg, so a change to the PostgreSQL matrix means updating that URL. A leg that no longer exists renders as
unknownrather than failing, which is a quiet way to go stale.
Test plan
Docs and README only, no CI behavior change. markdownlint, Vale and lychee (with --include-fragments, which checks the README's #coverage-strategy link) all pass with zero errors.