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

New issue

Closed

opened 2026-09-17 14:12:58 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

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

Owner

docs/PLAN.md calls itself "a living document, revised as milestones land and assumptions
meet reality". Its last revision is b3b7adfa1, 2026-09-09 — before the 0.2.0 release,
before 0.3.0 and its 107 issues, before the wiki moved out, before the audit. A plan that
is a week behind is not a plan, it is a record of what somebody used to intend, and this
one is the document that explains why the code is shaped the way it is. That is the part
nobody can reconstruct from the repository, which is exactly why it has to be kept true.

Concretely, what is wrong now:

The status line and the milestone tables

The banner (line 3) says "the 0.2.0 milestone complete and unreleased; 0.3.0 onward in
progress". 0.2.0 was released 2026-09-07 and 0.3.0 on 2026-09-16.
The 0.2.0 row says Complete, unreleased; the 0.3.0 row says In progress. Both
milestones are closed in Forgejo — 72 and 107 issues.
1.0.0 exists as a milestone and is not in the table at all. Neither is what the table
promised for 0.3.0 against what 0.3.0 actually was: the row says right-to-left layout, the
languages of Africa, parent and child companies, and reports on the regularity of a search,
and the African catalogues did not land there. The numbered table should say what each
milestone holds, or stop restating the tracker and point at it — the banner already says
the tracker is the authority.

Section 4, the repository layout

"the seven Postulo ships" — there are fifteen in-tree plugins now: browser, builtin,
email, email_addresses, employer_structure, europass, identifiers, localstore,
own_mail, phone_numbers, postal_rules, repositories, smtp, social_profiles,
websites. The tree names four of them.
notifications/ is missing from the tree, and it is not a small app.
docs/ is listed as holding INSTALL.md, which does not exist; the directory holds
PLAN.md, PLUGINS.md, THREAT-MODEL.md and TRANSLATING.md. THREAT-MODEL.md is the
one worth naming, given how much of 0.3.0 answered to it.
The wiki is not mentioned. It became a repository of its own on 2026-09-10 (#169), and
so did the plugins that live outside — postulo-imap, -apprise, -dav, -paperless,
-mcp, the two browser extensions, postulo-helloworld and postulo-templates. A reader
of the layout section has no way to learn any of that exists.

Section 9, the open assumptions

Assumption 3 is false now. "Nothing queues work yet, so no worker runs" — django_tasks_db
is in INSTALLED_APPS, TASKS names the database backend, core/scheduler.py holds the
lease and the heartbeat, and db_worker is enough of a fixture that config/sqlite.py and
documents/views.py both reason about not blocking it. The thing the assumption said to
re-check when something queued work has happened; the entry should record the answer.
Assumption 4 has an address now. It says what depends on contributors is review —
every catalogue complete, none read by a speaker. Since 2026-09-16 that review has a place
to happen: Weblate at translate.tiagoagueda.com, 21 components, pulling read-only from
Forgejo. That belongs in the plan, and so does the consequence the assumption did not
foresee: translations now accumulate somewhere that is not the repository, and somebody has
to bring them back.
Line 35 still says drafts are "marked fuzzy". They are flagged draft.

What would keep it true

Revising it once now leaves it a week stale again by 0.5.0. Two candidates worth choosing
between while doing the revision:

Fold the revision into the release checklist in CONTRIBUTING.md, beside the README
and wiki status lines that already get updated at a tag. The plan's own banner is the same
kind of line.
Let the plan stop tracking state. Sections 8 and the banner exist to say where we are,
which Forgejo already answers and answers correctly. If they went, what remains — mission,
product decisions, stack, layout, data model, plugin architecture, assumptions — goes stale
slowly and for real reasons, which is the kind of staleness a revision can catch.

Related: #254, which is about the same failure in the other direction — the changelog says
too much because nothing decided what it was for.

`docs/PLAN.md` calls itself "a living document, revised as milestones land and assumptions meet reality". Its last revision is `b3b7adfa1`, **2026-09-09** — before the 0.2.0 release, before 0.3.0 and its 107 issues, before the wiki moved out, before the audit. A plan that is a week behind is not a plan, it is a record of what somebody used to intend, and this one is the document that explains *why the code is shaped the way it is*. That is the part nobody can reconstruct from the repository, which is exactly why it has to be kept true. Concretely, what is wrong now: ## The status line and the milestone tables - **The banner** (line 3) says "the 0.2.0 milestone complete and unreleased; 0.3.0 onward in progress". 0.2.0 was released 2026-09-07 and 0.3.0 on 2026-09-16. - **The 0.2.0 row** says *Complete, unreleased*; **the 0.3.0 row** says *In progress*. Both milestones are closed in Forgejo — 72 and 107 issues. - **1.0.0 exists as a milestone and is not in the table at all.** Neither is what the table promised for 0.3.0 against what 0.3.0 actually was: the row says right-to-left layout, the languages of Africa, parent and child companies, and reports on the regularity of a search, and the African catalogues did not land there. The numbered table should say what each milestone *holds*, or stop restating the tracker and point at it — the banner already says the tracker is the authority. ## Section 4, the repository layout - **"the seven Postulo ships"** — there are fifteen in-tree plugins now: `browser`, `builtin`, `email`, `email_addresses`, `employer_structure`, `europass`, `identifiers`, `localstore`, `own_mail`, `phone_numbers`, `postal_rules`, `repositories`, `smtp`, `social_profiles`, `websites`. The tree names four of them. - **`notifications/` is missing** from the tree, and it is not a small app. - **`docs/` is listed as holding `INSTALL.md`**, which does not exist; the directory holds `PLAN.md`, `PLUGINS.md`, `THREAT-MODEL.md` and `TRANSLATING.md`. `THREAT-MODEL.md` is the one worth naming, given how much of 0.3.0 answered to it. - **The wiki is not mentioned.** It became a repository of its own on 2026-09-10 (#169), and so did the plugins that live outside — `postulo-imap`, `-apprise`, `-dav`, `-paperless`, `-mcp`, the two browser extensions, `postulo-helloworld` and `postulo-templates`. A reader of the layout section has no way to learn any of that exists. ## Section 9, the open assumptions - **Assumption 3 is false now.** "Nothing queues work yet, so no worker runs" — `django_tasks_db` is in `INSTALLED_APPS`, `TASKS` names the database backend, `core/scheduler.py` holds the lease and the heartbeat, and `db_worker` is enough of a fixture that `config/sqlite.py` and `documents/views.py` both reason about not blocking it. The thing the assumption said to re-check when something queued work has happened; the entry should record the answer. - **Assumption 4 has an address now.** It says what depends on contributors is *review* — every catalogue complete, none read by a speaker. Since 2026-09-16 that review has a place to happen: Weblate at translate.tiagoagueda.com, 21 components, pulling read-only from Forgejo. That belongs in the plan, and so does the consequence the assumption did not foresee: translations now accumulate somewhere that is not the repository, and somebody has to bring them back. - Line 35 still says drafts are "marked fuzzy". They are flagged `draft`. ## What would keep it true Revising it once now leaves it a week stale again by 0.5.0. Two candidates worth choosing between while doing the revision: - **Fold the revision into the release checklist** in `CONTRIBUTING.md`, beside the README and wiki status lines that already get updated at a tag. The plan's own banner is the same kind of line. - **Let the plan stop tracking state.** Sections 8 and the banner exist to say *where we are*, which Forgejo already answers and answers correctly. If they went, what remains — mission, product decisions, stack, layout, data model, plugin architecture, assumptions — goes stale slowly and for real reasons, which is the kind of staleness a revision can catch. Related: #254, which is about the same failure in the other direction — the changelog says too much because nothing decided what it was for.

tiagoagueda added this to the 0.4.0 milestone

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

tiagoagueda added the

documentation

label

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

tiagoagueda commented

2026-09-17 18:00:17 +00:00

Author

Owner

Notice which parts went stale

Every error listed above is in a part of the document that is derivable from the
repository: seven plugins where there are fifteen, a missing notifications/, an
INSTALL.md that does not exist, a wiki and eight sibling repositories that are not
mentioned. Sections 1, 2, 6 and 7 — mission, product decisions, self-hosting, plugin
architecture — are the parts a person has to write, and they did not rot.

That is the useful pattern here. Revising section 4 by hand fixes it until the sixteenth
plugin lands, and then it is wrong again, silently, and nobody finds out for a week.

This project already knows what to do about that. tests/test_changelog.py guards the
shape of a file nobody would otherwise check, and tests/test_stylesheet.py fails when the
committed CSS goes stale against its source. The same move applies:

a test that walks src/postulo/plugins/ and fails when section 4's list is not the set on
disk;
the same for the top-level apps in the layout tree;
the same for the contents of docs/.

Small tests, and they turn "revise the plan" from a recurring chore into a one-off.

Where a package might come in, and why it is the weaker half

django-extensions ships graph_models, which renders the model graph from the ORM. It is
the obvious suggestion for section 5 (Data model) — and on inspection PLAN.md has no
diagram at all today, so this would be adding something rather than automating something.

That makes it a real but separate proposal: if section 5 would be clearer with a generated
diagram, graph_models produces one and it never goes stale. If it would not, the package
earns nothing here, because everything else it offers (shell_plus, show_urls,
runserver_plus) is developer convenience with no bearing on this issue.

Recommendation: fix the prose, and add the three tests. Treat the diagram as its own
decision, and do not add a dependency for it unless section 5 actually wants one.

## Notice which parts went stale Every error listed above is in a part of the document that is **derivable from the repository**: seven plugins where there are fifteen, a missing `notifications/`, an `INSTALL.md` that does not exist, a wiki and eight sibling repositories that are not mentioned. Sections 1, 2, 6 and 7 — mission, product decisions, self-hosting, plugin architecture — are the parts a person has to write, and they did not rot. That is the useful pattern here. Revising section 4 by hand fixes it until the sixteenth plugin lands, and then it is wrong again, silently, and nobody finds out for a week. **This project already knows what to do about that.** `tests/test_changelog.py` guards the shape of a file nobody would otherwise check, and `tests/test_stylesheet.py` fails when the committed CSS goes stale against its source. The same move applies: - a test that walks `src/postulo/plugins/` and fails when section 4's list is not the set on disk; - the same for the top-level apps in the layout tree; - the same for the contents of `docs/`. Small tests, and they turn "revise the plan" from a recurring chore into a one-off. ### Where a package might come in, and why it is the weaker half `django-extensions` ships `graph_models`, which renders the model graph from the ORM. It is the obvious suggestion for section 5 (*Data model*) — and on inspection **PLAN.md has no diagram at all today**, so this would be adding something rather than automating something. That makes it a real but separate proposal: if section 5 would be clearer with a generated diagram, `graph_models` produces one and it never goes stale. If it would not, the package earns nothing here, because everything else it offers (`shell_plus`, `show_urls`, `runserver_plus`) is developer convenience with no bearing on this issue. Recommendation: fix the prose, and add the three tests. Treat the diagram as its own decision, and do not add a dependency for it unless section 5 actually wants one.

tiagoagueda referenced this issue from a commit

2026-09-19 11:25:58 +00:00

Let the plan stop restating where the project stands

tiagoagueda closed this issue

2026-09-19 11:25:58 +00:00