cb3d28e3d6
README: rewritten around what runs (Linux software, Xorg, apk, Linux's drivers), the honest gaps, measured numbers. plan/: 1.0.md is the finish line, where each clause of the acceptance test stands, and the register (one failing clause: a root that survives a reboot); built plans (foundations, hybrid, alpine, xorg) and the decided-against one (wayland) are gone, their content lives in architecture/; roadmap.md is only what is still open. guides: building/layout/testing/adding-a-driver (Linux code may be used). history: four entries (ls -lR, TLB shootdowns, MDIO 0x02460246, netlink MSG_TRUNC). Website: cards, stack, download page, docs index. Code comments that pointed at deleted plan docs point at the architecture docs. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao
54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
# History
|
|
|
|
**Why SchOS is the way it is.** Bugs whose cause was nowhere near their symptom,
|
|
and the few write-ups that have nowhere better to live.
|
|
|
|
| | |
|
|
|---|---|
|
|
| [kernel.md](kernel.md) | The expensive ones. Boot, SMP, signals, ABI assumptions, `/proc`, input, TLBs, a stub that returned a flag word. |
|
|
| [schfs.md](schfs.md) | How the filesystem was built, and what each phase cost. |
|
|
| [moving-to-linux.md](moving-to-linux.md) | The Windows-to-Fedora move. |
|
|
|
|
---
|
|
|
|
## What belongs in here
|
|
|
|
> **A bug whose cause is not visible from the code that fixed it.**
|
|
|
|
That is the whole test. If reading the fix explains the problem, the fix is the
|
|
documentation and nothing needs writing down. If the fix looks arbitrary — a
|
|
constant moved by eight, a field reordered, a check inverted — then the
|
|
strangeness is load-bearing and the next person to touch it deserves to know
|
|
why before they change it back.
|
|
|
|
Every entry here is a thing that looked like a different problem than it was.
|
|
|
|
## What does not belong
|
|
|
|
- **A changelog.** `git log` is the changelog.
|
|
- **A bug that was found and fixed in an hour.** Cost is the filter.
|
|
- **How something works.** That is [../architecture/](../architecture/), written
|
|
in the present tense for somebody who does not care what it used to be.
|
|
- **Anything still open.** An unfinished investigation goes in
|
|
[../plan/](../plan/) or in the code as a comment. This directory is past tense.
|
|
|
|
## How to write one
|
|
|
|
**Symptom first, then diagnosis, then the fix, then the transferable part.**
|
|
|
|
The transferable part is the reason the entry exists. `__thread` being wrong for
|
|
per-CPU data is worth more than the specific null dereference it caused;
|
|
"a layout constant that several artifacts must agree on wants a check that stops
|
|
the build, not a comment asking people to remember" is worth more than the
|
|
bootloader offset that taught it.
|
|
|
|
**Say how it was found**, when the technique was the hard part. A hardware
|
|
watchpoint through QEMU's gdb stub named an instruction on the first run after
|
|
three rounds of `cprintf` had narrowed it to nothing — that is reusable, and the
|
|
bug is not.
|
|
|
|
**Do not clean up the embarrassing part.** The near-miss where a change passed
|
|
every assertion green *without having been applied at all* is one of the most
|
|
useful entries in this directory, and it only works because it admits that a
|
|
`grep` returning three hits was read as confirmation without counting what they
|
|
were.
|