26 lines
1.2 KiB
Markdown
26 lines
1.2 KiB
Markdown
# Tidying the repository root
|
|
|
|
The root had thirty-odd files in it, nine of them session reports sitting at the
|
|
same level as the language specification, and a README is about to point a
|
|
newcomer at that. This is the plan and, below it, what actually happened.
|
|
|
|
## The plan
|
|
|
|
1. `git mv` the nine `HANDOFF-*.md` into `docs/handoffs/`, and `../DISCUSS.md`,
|
|
`../BUILT.md`, `../PORTING.md`, `../SPIKE-GENERICS.md`, `../REFERENCES.md` and
|
|
`../overview.md` into `docs/`. These are written once and read occasionally.
|
|
2. Leave `plan.org`, `spec-memory.md`, `spec-conditions.md`, `NEXT.md`, the
|
|
`.flan` scratch programs and the build files where they are: they are cited
|
|
by bare filename from source comments in dozens of places, and moving them
|
|
would be a large rewrite for no gain.
|
|
3. Rewrite every citation of a moved file, zone by zone — a flat substitution is
|
|
wrong, because a citation inside `docs/` should stay bare while the same
|
|
citation in `lib/` needs the `docs/` prefix.
|
|
4. Verify by resolving, not by grepping: for every cited path in the repository,
|
|
check it exists relative to the citing file or to the root.
|
|
5. Write `docs/README.md` saying which of these documents are still true.
|
|
|
|
## What happened
|
|
|
|
(filled in as the work lands)
|