Keep the wiki in its own repository, and stop copying it there #169

New issue

Closed

opened 2026-09-10 11:55:03 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-09-10 11:55:03 +00:00

Owner

Decision

The wiki has one home: the postulo.wiki repository. Its pages are written and committed there, directly. postulo/wiki/ and scripts/publish-wiki.sh go.

Why

Two copies drift, and this pair already had. wiki/ was the source and the Forgejo wiki a copy, refreshed only when somebody remembered to run the script. The last publish was on 5 September (9645ee1). Since then:

four pages never reached the wiki: Accessibility, Hardening, Listings and Reports;
all seventeen others were out of date;
the images never reached it at all. The script copies *.md and nothing else, so the logo and the Buy me a coffee button on Home have never shown on the published wiki.

What it changes

postulo.wiki takes every page as of postulo@b6cfb8f7 and the images/ directory. Its history until now is nothing but publish commits, and I checked that nothing was edited there that wiki/ did not already have.
postulo loses wiki/ and the script. CONTRIBUTING.md and CLAUDE.md say where pages are written now, and the guidance that lived in wiki/README.md moves to CONTRIBUTING.md: page names, links between pages, and keeping it honest.
The rule stays: a feature ships with its wiki page. The page is now a commit in the wiki repository naming the same issue, rather than a file in the same commit.

Worth being careful about

The review-alongside-code argument was the reason for wiki/. It is weaker than it looked, because nothing ever enforced the publish step. With the wiki committed directly, what readers see is what was written.
Forgejo resolves a wiki page's relative image paths against the wiki repository, so images/postulo.png works once the file is there. That needs checking on the rendered page, not assuming.

## Decision The wiki has one home: the `postulo.wiki` repository. Its pages are written and committed there, directly. `postulo/wiki/` and `scripts/publish-wiki.sh` go. ## Why Two copies drift, and this pair already had. `wiki/` was the source and the Forgejo wiki a copy, refreshed only when somebody remembered to run the script. The last publish was on 5 September (`9645ee1`). Since then: - **four pages never reached the wiki**: *Accessibility*, *Hardening*, *Listings* and *Reports*; - **all seventeen others were out of date**; - **the images never reached it at all.** The script copies `*.md` and nothing else, so the logo and the *Buy me a coffee* button on *Home* have never shown on the published wiki. ## What it changes - **`postulo.wiki`** takes every page as of `postulo@b6cfb8f7` and the `images/` directory. Its history until now is nothing but publish commits, and I checked that nothing was edited there that `wiki/` did not already have. - **`postulo`** loses `wiki/` and the script. `CONTRIBUTING.md` and `CLAUDE.md` say where pages are written now, and the guidance that lived in `wiki/README.md` moves to `CONTRIBUTING.md`: page names, links between pages, and keeping it honest. - **The rule stays**: a feature ships with its wiki page. The page is now a commit in the wiki repository naming the same issue, rather than a file in the same commit. ## Worth being careful about - **The review-alongside-code argument** was the reason for `wiki/`. It is weaker than it looked, because nothing ever enforced the publish step. With the wiki committed directly, what readers see is what was written. - **Forgejo resolves a wiki page's relative image paths against the wiki repository**, so `images/postulo.png` works once the file is there. That needs checking on the rendered page, not assuming.

tiagoagueda added this to the 0.3.0 milestone

2026-09-10 11:55:03 +00:00

tiagoagueda added the

documentation

label

2026-09-10 11:55:03 +00:00

tiagoagueda referenced this issue from a commit

2026-09-10 12:02:11 +00:00

Write the wiki in its own repository, and stop keeping a copy here

tiagoagueda commented

2026-09-10 12:02:56 +00:00

Author

Owner

Done, in both repositories:

postulo.wiki@2d4c0c7 takes every page as of postulo@b6cfb8f7: the four that had never been published (Accessibility, Hardening, Listings, Reports), the seventeen that were stale, and images/.
postulo@a22e7a09 removes wiki/ and scripts/publish-wiki.sh. CONTRIBUTING.md says where pages are written now: where to clone the wiki, how pages and links are named, and where images go, taking over what wiki/README.md said. CLAUDE.md and the README point at the wiki repository, and .dockerignore loses its wiki line.

Checked on the live wiki

Every page loads without signing in; I fetched Home, Accessibility, Hardening, Listings, Reports and CVs.
The images render now. Forgejo rewrites Home's relative images/postulo.png to /postulo/postulo/wiki/raw/images/postulo.png. Both images come back as real PNGs, of the same byte size as the files, so the front page shows its logo and button for the first time.
Before replacing anything, I confirmed the wiki held nothing that wiki/ did not. Its history was nothing but publish commits, and the pages matched wiki/ at 9645ee1 byte for byte, apart from line endings in the checkout.

Still true

A feature ships with its wiki page. It is now a commit to postulo.wiki that names the same issue.

Done, in both repositories: - **`postulo.wiki@2d4c0c7`** takes every page as of `postulo@b6cfb8f7`: the four that had never been published (*Accessibility*, *Hardening*, *Listings*, *Reports*), the seventeen that were stale, and `images/`. - **`postulo@a22e7a09`** removes `wiki/` and `scripts/publish-wiki.sh`. `CONTRIBUTING.md` says where pages are written now: where to clone the wiki, how pages and links are named, and where images go, taking over what `wiki/README.md` said. `CLAUDE.md` and the README point at the wiki repository, and `.dockerignore` loses its `wiki` line. ## Checked on the live wiki - Every page loads without signing in; I fetched Home, Accessibility, Hardening, Listings, Reports and CVs. - **The images render now.** Forgejo rewrites Home's relative `images/postulo.png` to `/postulo/postulo/wiki/raw/images/postulo.png`. Both images come back as real PNGs, of the same byte size as the files, so the front page shows its logo and button for the first time. - Before replacing anything, I confirmed the wiki held nothing that `wiki/` did not. Its history was nothing but publish commits, and the pages matched `wiki/` at `9645ee1` byte for byte, apart from line endings in the checkout. ## Still true A feature ships with its wiki page. It is now a commit to `postulo.wiki` that names the same issue.

tiagoagueda closed this issue

2026-09-10 12:03:21 +00:00

tiagoagueda referenced this issue

2026-09-10 12:22:18 +00:00

The wiki should document the whole API surface: the machine endpoints and the plugin API #170

tiagoagueda referenced this issue from a commit

2026-09-10 12:37:08 +00:00

Move the plugin guide into the wiki, and hold the wiki to the API surface

tiagoagueda referenced this issue

2026-09-17 14:12:58 +00:00

docs/PLAN.md has not been revised since before 0.3.0 and now says untrue things #255