Repo cleanup: move root design docs to the wiki (update or drop if outdated) #26

New issue

Closed

opened 2026-08-30 12:50:16 +02:00 by orkun · 1 comment

orkun commented

2026-08-30 12:50:16 +02:00

Owner

Problem

The repository root is cluttered with 11 large Markdown files (~330 KB total),
most of them long-lived design documents rather than things a newcomer needs on
first contact:

File	Size	Nature
`LUANTI-ROADMAP.md`	63 KB	roadmap / design
`BOOTSTRAP.md`	50 KB	deep-dive
`EVENTS-DESIGN.md`	41 KB	design
`LANGUAGE.md`	41 KB	reference
`NETWORKING-DESIGN.md`	29 KB	design
`SYNTAX-REDESIGN.md`	21 KB	design
`LIFECYCLE-DESIGN.md`	19 KB	design
`MOBILE-DESIGN.md`	18 KB	design
`COMPILING.md`	17 KB	reference
`SCENES-DESIGN.md`	16 KB	design
`README.md`	10 KB	entry point

A design doc dump at the root buries the README, makes the repo hard to scan, and
mixes "how to use Ludic" with "how we decided to build Ludic."

Proposal

Move the design/roadmap docs to the repository wiki (the wiki is not yet
initialised — enable it in Forgejo repo settings first), leaving the root to
README.md plus at most the genuine user-facing references (LANGUAGE.md,
COMPILING.md) — or fold those into docs/ too.

For each file, decide per the request's rule:

Still accurate → move to the wiki and update it if it drifted from reality.
Outdated / superseded → do not move it. Delete it (git history preserves it).

Suggested wiki structure: Design/Events, Design/Networking, Design/Scenes,
Design/Lifecycle, Design/Mobile, Design/Syntax-Redesign, Bootstrap,
Roadmap/Luanti.

Acceptance criteria

Wiki enabled and populated with the still-relevant design docs.
Each moved doc reviewed for staleness and updated, or dropped if outdated.
Root contains only README.md (+ deliberately-kept references).
README links to the wiki for the design material.

Part of the repository-cleanup / DX pass.

## Problem The repository root is cluttered with **11 large Markdown files** (~330 KB total), most of them long-lived design documents rather than things a newcomer needs on first contact: | File | Size | Nature | |------|------|--------| | `LUANTI-ROADMAP.md` | 63 KB | roadmap / design | | `BOOTSTRAP.md` | 50 KB | deep-dive | | `EVENTS-DESIGN.md` | 41 KB | design | | `LANGUAGE.md` | 41 KB | reference | | `NETWORKING-DESIGN.md` | 29 KB | design | | `SYNTAX-REDESIGN.md` | 21 KB | design | | `LIFECYCLE-DESIGN.md` | 19 KB | design | | `MOBILE-DESIGN.md` | 18 KB | design | | `COMPILING.md` | 17 KB | reference | | `SCENES-DESIGN.md` | 16 KB | design | | `README.md` | 10 KB | entry point | A design doc dump at the root buries the README, makes the repo hard to scan, and mixes "how to use Ludic" with "how we decided to build Ludic." ## Proposal Move the **design/roadmap docs** to the repository **wiki** (the wiki is not yet initialised — enable it in Forgejo repo settings first), leaving the root to `README.md` plus at most the genuine user-facing references (`LANGUAGE.md`, `COMPILING.md`) — or fold those into `docs/` too. For each file, decide per the request's rule: - **Still accurate** → move to the wiki and update it if it drifted from reality. - **Outdated / superseded** → do **not** move it. Delete it (git history preserves it). Suggested wiki structure: `Design/Events`, `Design/Networking`, `Design/Scenes`, `Design/Lifecycle`, `Design/Mobile`, `Design/Syntax-Redesign`, `Bootstrap`, `Roadmap/Luanti`. ## Acceptance criteria - [ ] Wiki enabled and populated with the still-relevant design docs. - [ ] Each moved doc reviewed for staleness and updated, or dropped if outdated. - [ ] Root contains only `README.md` (+ deliberately-kept references). - [ ] README links to the wiki for the design material. Part of the repository-cleanup / DX pass.

orkun added the

labels 2026-08-30 12:50:16 +02:00

orkun referenced this issue from a commit

2026-08-30 23:36:22 +02:00

docs: move design/roadmap docs to the wiki, trim the repo root

orkun closed this issue

2026-08-30 23:36:22 +02:00

orkun commented

2026-08-30 23:36:41 +02:00

Author

Owner

Done in c040fff (repo) + the wiki push.

Wiki enabled and populated — https://git.workshopsoft.io/workshopsoft/ludic/wiki

Page	From
Design/Events	`EVENTS-DESIGN.md`
Design/Networking	`NETWORKING-DESIGN.md`
Design/Scenes	`SCENES-DESIGN.md`
Design/Lifecycle	`LIFECYCLE-DESIGN.md`
Design/Mobile	`MOBILE-DESIGN.md`
Design/Syntax-Redesign	`SYNTAX-REDESIGN.md`
Bootstrap	`BOOTSTRAP.md`
Roadmap/Luanti	`LUANTI-ROADMAP.md`

Plus a Home index and a _Sidebar for navigation.

Staleness review: all eight are current, actively-maintained design records (all last touched in the most recent doc pass), so none were dropped. Each was updated during the move rather than copied verbatim:

every selfhost/… source link was corrected for the concern-based reorg (#29) — e.g. selfhost/emit_save.ludic → selfhost/backend/game/emit_save.ludic;
every repo-relative link was rewritten to an absolute URL on main so it resolves from the wiki;
cross-doc links now point at the sibling wiki pages.

Root trimmed — the remaining root Markdown is README.md + the two user-facing references (LANGUAGE.md, COMPILING.md), plus the standard CONTRIBUTING.md / CODE_OF_CONDUCT.md / CHANGELOG.md. The design-doc dump is gone.

Links rewired: the README now points to the wiki for the design material; the stragglers in LANGUAGE.md, COMPILING.md, examples/README.md and the emit_net.ludic header comment point at the wiki pages. (The emit_net.ludic edit is a comment only — seed stays byte-identical, x bootstrap-cfree + x test (56) green.)

All four acceptance criteria met: wiki enabled + populated; each doc reviewed for staleness (updated, none stale enough to drop); root is README + deliberately-kept references; README links to the wiki. Deleted docs remain in git history.

Done in c040fff (repo) + the wiki push. **Wiki enabled and populated** — https://git.workshopsoft.io/workshopsoft/ludic/wiki | Page | From | |---|---| | [Design/Events](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FEvents) | `EVENTS-DESIGN.md` | | [Design/Networking](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FNetworking) | `NETWORKING-DESIGN.md` | | [Design/Scenes](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FScenes) | `SCENES-DESIGN.md` | | [Design/Lifecycle](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FLifecycle) | `LIFECYCLE-DESIGN.md` | | [Design/Mobile](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FMobile) | `MOBILE-DESIGN.md` | | [Design/Syntax-Redesign](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Design%2FSyntax-Redesign) | `SYNTAX-REDESIGN.md` | | [Bootstrap](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Bootstrap) | `BOOTSTRAP.md` | | [Roadmap/Luanti](https://git.workshopsoft.io/workshopsoft/ludic/wiki/Roadmap%2FLuanti) | `LUANTI-ROADMAP.md` | Plus a **Home** index and a **_Sidebar** for navigation. **Staleness review:** all eight are current, actively-maintained design records (all last touched in the most recent doc pass), so none were dropped. Each was *updated* during the move rather than copied verbatim: - every `selfhost/…` source link was corrected for the concern-based reorg (#29) — e.g. `selfhost/emit_save.ludic` → `selfhost/backend/game/emit_save.ludic`; - every repo-relative link was rewritten to an absolute URL on `main` so it resolves from the wiki; - cross-doc links now point at the sibling wiki pages. **Root trimmed** — the remaining root Markdown is `README.md` + the two user-facing references (`LANGUAGE.md`, `COMPILING.md`), plus the standard `CONTRIBUTING.md` / `CODE_OF_CONDUCT.md` / `CHANGELOG.md`. The design-doc dump is gone. **Links rewired:** the README now points to the wiki for the design material; the stragglers in `LANGUAGE.md`, `COMPILING.md`, `examples/README.md` and the `emit_net.ludic` header comment point at the wiki pages. (The `emit_net.ludic` edit is a comment only — seed stays byte-identical, `x bootstrap-cfree` + `x test` (56) green.) All four acceptance criteria met: wiki enabled + populated; each doc reviewed for staleness (updated, none stale enough to drop); root is README + deliberately-kept references; README links to the wiki. Deleted docs remain in git history.

orkun referenced this issue

2026-09-01 12:34:25 +02:00

Proposal: comprehensive Tiled (TMX/TMJ) map support — parse & consume every Tiled feature/output #66