nexoniarz/SchOS
nexoniarz/SchOS
Watch
1
0
Fork
You've already forked SchOS
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: four directories, and a rule for when a thing leaves the roadmap

Browse source 
docs/ was ten files where a plan, a description, a guide and a bug report all
sat next to each other. It is now architecture/ (what SchOS is), plan/ (what it
will be), guides/ (how to work on it) and history/ (why it is like this), with
an index that states the one rule holding it together: when something is
finished it moves from plan/ to architecture/ and is rewritten as a description
of the thing rather than a record of building it.

A ticked checkbox says the work happened. It does not say what the work
*produced*, and six months later the checkbox is all that is left. The network
stack proved the point: finished, verified end to end, and for a month the only
description of it anywhere was a checkbox four levels of indentation deep.

So roadmap.md went from 534 lines to 181 -- nothing deleted, the done work
graduated. Seven subsystems that were finished and undescribed now have
descriptions: boot, kernel, syscalls, filesystem, networking, graphics, usb,
init. Every one ends with "What it does not do", which is the section that pays;
a document listing only strengths is marketing, and the reader who needs it most
is the one about to trip over a limitation nobody wrote down.

schfs.md still opened with "phases 1 through 3 1/2 are done, phase 4 is next"
long after all five had landed. It is a description now, with the phase record
and the hard-won bugs moved to history/.

Three corrections found on the way, all load-bearing:

  * projects/schcom/README.md claimed SCM_RIGHTS was done. There is no
    sendmsg/recvmsg in the kernel at all, and an entire GUI plan rested on it.
  * The root README said "No TCP/IP" months after the stack landed.
  * history/kernel.md sec.7 was marked "in progress" on a problem that process
    groups solved.

Also adds plan/1.0.md, which draws a finish line so the open list stops being
infinite, and marks schwm/ and schde/ superseded: in Wayland the compositor is
the window manager, so that split dissolves rather than being abandoned.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
This commit is contained in:
Nexoniarz 2026-09-12 17:13:35 +02:00
commit 57aff40228
59 changed files with 3981 additions and 1124 deletions
Download patch file Download diff file Expand all files Collapse all files

129
docs/README.md Normal file
View file

@ -0,0 +1,129 @@
# SchOS documentation
Four kinds of document, kept in four directories, because they answer four
different questions and go stale at four different rates.
| | | |
|---|---|---|
| **[architecture/](architecture/)** | *What SchOS is* | Present tense. Describes what is built and working. |
| **[plan/](plan/)** | *What SchOS will be* | Future tense. Everything here is unbuilt. |
| **[guides/](guides/)** | *How to work on it* | Imperative. Build it, test it, add to it. |
| **[history/](history/)** | *Why it is the way it is* | Past tense. Bugs whose cause is not visible from the fix. |
Plus one rule that belongs to no category and applies to everything:
**[licensing.md](licensing.md)** — read it before copying anyone else's code in.
---
## The rule that keeps this from rotting
> **When something is finished, it moves from `plan/` to `architecture/` and is
> rewritten as a description of the thing rather than a record of building it.**
A completed item is not a ticked checkbox. A ticked checkbox says the work
happened; it does not say what the work *produced*, and six months later the
checkbox is the only thing left and it explains nothing.
So finishing a piece of work has three steps, and the third is not optional:
1. The code works and is tested.
2. The plan entry is deleted.
3. A description exists in `architecture/` written for somebody who was not
there — what it does, what shape it has, what it costs, and what it still
does not do.
This is not bookkeeping. The tree has already proved it necessary: the network
stack was finished, verified end to end, and for a month afterwards the only
description of it anywhere was a checkbox in a roadmap, four levels of
indentation deep, written in the past tense of somebody arguing for the work
rather than explaining the result.
**The "what it does not do" section is the one that pays.** Every description in
`architecture/` ends with one. A document that only lists a subsystem's
strengths is marketing, and the reader who most needs the document is the one
about to trip over a limitation nobody wrote down.
---
## Start here
**New to the tree** → [architecture/README.md](architecture/README.md), the
system layer by layer, then [guides/layout.md](guides/layout.md) for where the
files are.
**Trying to build it** → [guides/building.md](guides/building.md).
**Wondering what happens next** → [plan/1.0.md](plan/1.0.md), which is the finish line, then [plan/README.md](plan/README.md) for the order.
**Something is broken and it feels familiar** → [history/](history/). There is a
good chance it is in there.
---
## architecture/ — what SchOS is
| | |
|---|---|
| [README](architecture/README.md) | The system, layer by layer. Read first. |
| [boot.md](architecture/boot.md) | Firmware to the first userspace process. |
| [kernel.md](architecture/kernel.md) | SchIFT: memory, processes, scheduling, traps, signals, SMP. |
| [syscalls.md](architecture/syscalls.md) | The call table, and the Linux personality that lets real software run. |
| [filesystem.md](architecture/filesystem.md) | The VFS, the buffer cache, procfs, mounts. |
| [schfs.md](architecture/schfs.md) | SchFS: the copy-on-write root filesystem. |
| [devices.md](architecture/devices.md) | The device model, driver binding, the class vtables. |
| [usb.md](architecture/usb.md) | xHCI, the USB core, and the class drivers. |
| [graphics.md](architecture/graphics.md) | Framebuffer, text rendering, console, and the crash screen. |
| [networking.md](architecture/networking.md) | Drivers, lwIP, sockets — Unix and INET. |
| [init.md](architecture/init.md) | `schinit`, PID 1, and the job manifests. |
## plan/ — what SchOS will be
| | |
|---|---|
| [README](plan/README.md) | The three current decisions and the order they happen in. |
| [1.0.md](plan/1.0.md) | **The finish line.** What 1.0 contains, and what is explicitly deferred past it. |
| [foundations.md](plan/foundations.md) | The kernel work everything else is blocked on. |
| [init.md](plan/init.md) | PID 1 becomes a role rather than a process. |
| [wayland.md](plan/wayland.md) | The GUI stack, and what gets deleted to make room. |
| [hybrid.md](plan/hybrid.md) | Moving drivers out of the kernel. |
| [schapi.md](plan/schapi.md) | The long-term API layering, and the compatibility promise. |
| [roadmap.md](plan/roadmap.md) | Everything else still open. |
## guides/ — how to work on it
| | |
|---|---|
| [building.md](guides/building.md) | Prerequisites and the build, per host. |
| [testing.md](guides/testing.md) | The harnesses, and what each one actually proves. |
| [layout.md](guides/layout.md) | Repository map, and how to add a program or a port. |
| [adding-a-driver.md](guides/adding-a-driver.md) | Writing one, binding it, publishing its class vtable. |
## history/ — why it is the way it is
| | |
|---|---|
| [README](history/README.md) | What belongs in here and what does not. |
| [kernel.md](history/kernel.md) | Bugs whose cause was nowhere near their symptom. |
| [moving-to-linux.md](history/moving-to-linux.md) | The Windows-to-Fedora move, kept for the parts that recur. |
---
## Writing one of these
Four conventions, all of them observable in the existing files:
**State the cost.** Every design choice gave something up. A document that does
not say what is a document that will be argued with later by somebody who only
sees the downside.
**Prefer the measured number to the remembered one.** "500 of 3565 files carry
the advertising clause" is worth more than "some do", and it was worth the
minute it took to count.
**Write down the bug that shaped it.** Half the non-obvious code in this tree is
non-obvious because something failed once. If a design is strange, the strangeness
is load-bearing and the reader deserves to know why before changing it.
**No dates in headings.** A date in a heading turns a description into a
changelog, and the description is the thing with a long life. Dates belong in
`history/`, where they mean something.