1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
# Issue register — process
**Policy: do NOT create issues by default.** An issue here is a *nasty bug*:
something that blocks mission-critical behaviour, is non-deterministic or not
reproducible on demand, corrupts state, or spans subsystems such that a
single-session fix is unrealistic. Ordinary fixes, TODOs and feature work do
not get an issue — they live in the handoff and the code comments.
File an issue when **any** of these holds:
1. Reproducibility / liveness is variable (works sometimes, stalls others)
and the variance itself is the bug.
2. The failure blocks a 1.0 acceptance criterion (guest CUDA, multi-VM,
performance target, ...).
3. Cross-subsystem state (host module + guest driver + physical GPU +
userspace tools) is involved and the ownership of the fix is unclear.
4. The investigation has already burned more than one session without a
confirmed root cause.
## How to file
* Directory: `open-iov/debug/issue/`; solved ones move to
`open-iov/debug/issue/solved/` (never delete, never renumber).
* Filename: `issue-number-N.md` with the next free integer `N`
(`issue-number-1.md`, `issue-number-2.md`, ...). Create
`issue-number-N+1.md` as a copy of the template below — do not create
placeholder issues.
* Keep it **public-safe** (this directory is tracked): describe components,
behaviour and evidence (same rules as every tracked document).
* Reference evidence by artifact: session/log file names, counter lines,
commit hashes. Every claim needs its evidence pointer.
## Template
```markdown
# ISSUE-00NN: <one-line title>
* Status: OPEN | FIX IMPLEMENTED (VALIDATION PENDING) | SOLVED
* Filed: <date>, session <label> | Priority: <top/p1/p2> | Component: <kernel/guest/...>
## Symptom
What is observed, by whom, how often. Include the exact observable signature.
## Impact
Which acceptance criterion is blocked; what work is blocked behind it.
## Evidence
Logs/counters/commits that establish the facts. Include the one-line
discriminators between healthy and failing runs.
## Root cause
The causal chain established so far, with confidence and what is still
hypothesis (label uncertainty explicitly).
## Fix / fix plan
Code changes with commit hashes; for open items, the ordered plan and the
files/functions to touch.
## Validation plan
Acceptance criteria (numbers of consecutive runs, counters that must stay
zero, suites to run) and how the fix is rolled back if it regresses.
## History
Dated one-liners: what was tried, what it taught, what was rejected.
```
## Lifecycle
* OPEN: filed, root cause partial.
* FIX IMPLEMENTED (VALIDATION PENDING): code landed (committed) but the
acceptance runs have not completed on a live stack.
* SOLVED: acceptance criteria met with evidence; move the file to `solved/`
and add a `## Resolution` section (what fixed it, the validating runs,
residual risks). If the same failure returns, file a **new** number and
cross-reference — do not reopen the moved file.
|
