56 lines
1.5 KiB
Markdown
56 lines
1.5 KiB
Markdown
|
# Contributing to timmy-home
|
||
|
|
|
||
|
|
## Proof Standard
|
||
|
|
|
||
|
|
This is a hard rule.
|
||
|
|
|
||
|
|
- visual changes require screenshot proof
|
||
|
|
- keep screenshots and binary media out of Gitea backup unless explicitly required
|
||
|
|
- CLI/verifiable changes must reference the exact command output, log path, or observable state that proves acceptance criteria were met
|
||
|
|
- compile-only validation is not enough when stronger runtime or world-state proof is available
|
||
|
|
- no proof, no merge
|
||
|
|
|
||
|
|
## How to satisfy the rule
|
||
|
|
|
||
|
|
### Visual changes
|
||
|
|
Examples:
|
||
|
|
- browser UI
|
||
|
|
- dashboards
|
||
|
|
- render/layout changes
|
||
|
|
- skins or visible presentation changes landed through this workspace
|
||
|
|
|
||
|
|
Required proof:
|
||
|
|
- provide screenshot proof
|
||
|
|
- store screenshots outside the repo by default
|
||
|
|
- explain what the screenshot proves
|
||
|
|
|
||
|
|
### CLI / docs / scripts / harness-adjacent changes
|
||
|
|
Examples:
|
||
|
|
- scripts under `scripts/`
|
||
|
|
- training/export utilities
|
||
|
|
- report generators
|
||
|
|
- operational documentation that claims a system behavior is true
|
||
|
|
|
||
|
|
Required proof:
|
||
|
|
- cite the exact command used, and its output, or
|
||
|
|
- cite the exact log path, artifact path, or observable world-state proving the claim
|
||
|
|
|
||
|
|
Good:
|
||
|
|
- `python3 -m pytest tests/test_x.py -q` → `2 passed`
|
||
|
|
- `/Users/apayne/.timmy/reports/...`
|
||
|
|
- `/Users/apayne/.timmy/heartbeat/...`
|
||
|
|
|
||
|
|
Bad:
|
||
|
|
- "looks correct"
|
||
|
|
- "compiled fine"
|
||
|
|
- "should be working"
|
||
|
|
|
||
|
|
## Merge gate
|
||
|
|
|
||
|
|
A PR is only ready when the reader can answer:
|
||
|
|
1. what changed
|
||
|
|
2. what acceptance criteria were targeted
|
||
|
|
3. what proof demonstrates those criteria were met
|
||
|
|
|
||
|
|
If the proof is absent, the work is not ready to merge.
|