132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
---
|
||
id: PLN-0037
|
||
ticket: runtime-edge-test-plan
|
||
title: Plan - Runtime Edge Coverage Governance Foundation
|
||
status: open
|
||
created: 2026-04-20
|
||
completed:
|
||
tags: [tests, coverage, governance, ci]
|
||
---
|
||
|
||
## Briefing
|
||
|
||
This plan operationalizes the governance layer of `DEC-0020`.
|
||
Its goal is to turn the decision into concrete review and CI mechanics without changing the underlying coverage toolchain.
|
||
|
||
## Decisions de Origem
|
||
|
||
- `DEC-0020`
|
||
|
||
## Alvo
|
||
|
||
Define the repository-level mechanics for:
|
||
|
||
- global coverage gate continuity;
|
||
- domain-scoped coverage evidence during review;
|
||
- baseline tracking that can start at `0` per domain and tighten later;
|
||
- reviewer-visible rules for when domain tests are mandatory.
|
||
|
||
## Escopo
|
||
|
||
- Add repository commands or scripts for domain-oriented coverage evidence collection.
|
||
- Add repository-facing documentation that explains the global gate plus domain evidence workflow.
|
||
- Align CI/coverage outputs with the new governance model without replacing `llvm-cov`.
|
||
|
||
## Fora de Escopo
|
||
|
||
- Expanding firmware tests.
|
||
- Refactoring the monolithic runtime suite.
|
||
- Introducing hard domain coverage percentages above baseline `0`.
|
||
- Replacing Jenkins or `cargo llvm-cov`.
|
||
|
||
## Plano de Execucao
|
||
|
||
### Step 1 - Define the domain evidence interface
|
||
|
||
**What:**
|
||
Define how contributors and reviewers gather coverage evidence for `system/runtime`, `fs`, `asset/bank`, `firmware`, and `host-dependent`.
|
||
|
||
**How:**
|
||
Add one repository-visible command path that produces:
|
||
|
||
- existing global HTML/XML/JSON coverage artifacts;
|
||
- a documented procedure for mapping changed files/modules to one of the canonical domains;
|
||
- an initial baseline format that records per-domain coverage starting from `0`.
|
||
|
||
**File(s):**
|
||
- `Makefile`
|
||
- `scripts/`
|
||
- `README.md` or another repository-facing process document if more appropriate
|
||
|
||
### Step 2 - Add domain evidence helpers
|
||
|
||
**What:**
|
||
Introduce helper commands or scripts that make domain evidence collection reproducible.
|
||
|
||
**How:**
|
||
Prefer simple wrappers over new tooling. For example:
|
||
|
||
- capture `llvm-cov` JSON/HTML consistently;
|
||
- filter or summarize target files/modules for a domain;
|
||
- emit review-friendly evidence artifacts without changing the authoritative global gate.
|
||
|
||
**File(s):**
|
||
- `Makefile`
|
||
- `scripts/`
|
||
|
||
### Step 3 - Document the PR acceptance rule
|
||
|
||
**What:**
|
||
Publish the decision’s review contract in a place visible during development.
|
||
|
||
**How:**
|
||
Document that any PR touching a canonical domain must either:
|
||
|
||
- update/add tests for that domain; or
|
||
- justify why the observable contract did not change.
|
||
|
||
Document that domain coverage evidence is mandatory review input even when domain thresholds are still at baseline `0`.
|
||
|
||
**File(s):**
|
||
- `README.md`
|
||
- optional repo process document if the repository has a better canonical location
|
||
|
||
### Step 4 - Align CI outputs with the governance model
|
||
|
||
**What:**
|
||
Make the existing coverage pipeline clearly compatible with domain review.
|
||
|
||
**How:**
|
||
Keep the current global Jenkins gate unchanged while ensuring produced artifacts are sufficient for domain inspection.
|
||
If needed, archive additional summaries or helper outputs generated by the new scripts.
|
||
|
||
**File(s):**
|
||
- `files/config/Jenkinsfile`
|
||
- `Makefile`
|
||
|
||
## Criterios de Aceite
|
||
|
||
- [ ] The repository exposes a documented way to collect domain-oriented coverage evidence without replacing the global `llvm-cov` gate.
|
||
- [ ] Review guidance explicitly states when domain tests are mandatory.
|
||
- [ ] Domain baselines are represented in a form that can start at `0` and increase later.
|
||
- [ ] Existing global coverage enforcement remains intact.
|
||
|
||
## Tests / Validacao
|
||
|
||
### Automated
|
||
|
||
- Validate all added helper commands locally.
|
||
- Run the existing coverage pipeline end to end after the helper changes.
|
||
|
||
### Evidence
|
||
|
||
- Show that the global coverage artifacts still build.
|
||
- Show an example of domain evidence collection for at least one domain.
|
||
|
||
## Riscos
|
||
|
||
- Overdesigning domain evidence collection before real reviewer usage patterns exist.
|
||
- Accidentally creating a second competing coverage authority instead of a reviewer aid.
|
||
- Spreading policy text across too many documents and making the rule hard to find.
|
||
|