Durable context for ebuild — decisions and constraints that outlive one
session and are not recoverable from the code or the git history.
Write here when a future reader would otherwise repeat an argument that was already settled, or repeat a mistake that was already made.
- Decisions and the reason behind them, especially the options rejected.
- Constraints that are not visible in the code — a deadline, a compatibility promise, a hardware limitation, an external dependency's behaviour.
- Traps: things that look wrong but are deliberate, and things that look safe but break.
- Anything derivable by reading the code.
- Anything in the git log.
- Task status — that is TASKS.md.
- Standards — those are QUALITY.md, TESTING.md and SECURITY-STANDARDS.md.
Format: what was chosen, why, and what was rejected. The rejected option is the valuable half — without it the decision gets re-argued every time someone new notices the obvious-looking alternative.
| Date | Decision | Reason | Rejected alternative |
|---|---|---|---|
| — | None recorded yet. | — | — |
| Constraint | Source | Consequence if broken |
|---|---|---|
| — | — | — |
Things that look wrong but are deliberate, and things that look safe but break. Add an entry the first time something here costs someone an hour — that is the threshold, and it is deliberately low.
None recorded yet.
Rules for this file:
- Absolute dates. Never "last week" or "recently".
- One entry per fact. A paragraph covering three decisions gets skimmed.
- Delete an entry when it becomes false. A stale note is worse than a missing one, because it is trusted.
- If an entry is derivable from the code or the git log, it does not belong here.