# 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.