Wiki, CONTRIBUTING and planning documents: eleven passages describe the project before changes that have landed #406

New issue

Closed

opened 2026-10-01 10:46:28 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-10-01 10:46:28 +00:00

Owner

Found on 2026-09-29 in a read-only review of postulo at 95348908d and the wiki at de1f52467, reading the user, contributor and planning documents against the settings, forms, compose file, workflows, pyproject.toml and the issue tracker.

Checked again on 2026-10-01 against main at 0a5cad587: still present. The code is now at accounts/forms.py:450 (AccessibilityForm) and :465 (the label), and jobs/forms.py:142-146 (the upload's help text). In CONTRIBUTING.md the Scanning the image section is now at :520-552 (its first sentence at :522), the two earlier passages at :391 and :418, and the Translations paragraph at :285-287. In .forgejo/workflows/ci.yml the second actions/cache@v4 is now at :405 and actions/upload-artifact@v3 at :434. Assumption 3 in docs/PLAN.md is now at :328-335.

Eleven passages describe Postulo as it was before a change that has since landed. None is a defect in the code. Each sends somebody to a place that no longer exists, gives a command that fails, says something is missing that is there, or tells a contributor something false about what the build runs and what is planned; two of them contradict another section of the same file.

Related to #281, #156 and #255, all closed. #281 moved two settings to Settings → Accessibility and #156 put the image scan in the pipeline, but the pages that described the earlier state were not all updated (sections 1 and 6); #255 revised docs/PLAN.md, and sections 8 and 9 slipped past that revision or were overtaken by #247. This issue lists what those three left behind, and the passages of the same kind left by #264, #235, #247 and #269.

Paths in sections 1 to 5 are pages of the wiki; the rest are in the postulo repository.

1. Wiki: the accessibility choices are no longer under Appearance

Since #281 the order number on career entries and the single-key shortcuts live on Settings → Accessibility (core/settings_sections.py:44-51; accounts/forms.py:449, AccessibilityForm, with show_career_order, keyboard_shortcuts and nav_underline). Three pages still send people to Appearance:

Getting-started.md:38-41 describes them inside the Appearance bullet, and the list of sections has no Accessibility bullet at all.
Capturing-postings.md:119 says "Settings → Appearance → Keyboard shortcuts". The setting is now under Accessibility and is labelled "Let a single key do something" (accounts/forms.py:464).
Your-career-record.md:507-508 says "under Settings → Appearance".

2. Wiki: company logos accept SVG and keep their size

Tracking-applications.md:77-79 says "SVG is refused for now" and that whatever arrives is "re-encoded to a 256-pixel square". Since #264 an SVG is sanitised and kept as a vector, and a bitmap is re-encoded at its own size (jobs/forms.py:141-145, the upload's help text; jobs/logos.py:16-22).

3. Wiki: tagged PDFs are listed as still wanted

Roadmap.md:102-103 lists "Tagged PDFs" under Still wanted, not scheduled and links to Accessibility → Known gaps. documents/pdf.py:83 renders pdf/ua-1, Accessibility.md:187 says "They are tagged", and its Known gaps no longer mentions PDFs (#235).

4. Wiki: `docker logs postulo` names no container

Troubleshooting.md:17 says docker logs postulo. docker/compose.yml:19 sets the project name: postulo, the service is postulo and there is no container_name, so the container is postulo-postulo-1 and the command answers "No such container". Every other page uses docker compose -f docker/compose.yml ….

5. Wiki: outbound webhooks are described as not built

The-capture-API.md:295-297 says outbound webhooks "are a separate feature and not built yet". Webhooks.md documents them. Its event table has no deletion event, so the paragraph's point (a mirror must notice absences itself) still stands; only the reason given is wrong.

6. `CONTRIBUTING.md`: "Scanning the image" says nothing scans the image

CONTRIBUTING.md:518-550. Line 520 says "Nothing scans the image yet — that needs a runner that can build one, and is #156", and gives two manual commands that run unpinned scanner images (aquasec/trivy, anchore/grype) against postulo:latest. About a hundred lines earlier, :389 and :416 say that scripts/scan-image.sh scans both the dev image and the release image before they are pushed, and .forgejo/workflows/image.yml:127 and .forgejo/workflows/dev-image.yml:126 call it. #156 is closed. The script pins aquasec/trivy:0.74.0 and anchore/grype:v0.100.0 (scripts/scan-image.sh:58, :62) and records why the pin matters.

A reader who lands on this section first concludes that there is no gate, and anyone who follows its commands runs whatever scanner image is current, which the script's own comments explain is unreliable.

7. `CONTRIBUTING.md`: the Translations paragraph

CONTRIBUTING.md:283-285 says "French and Portuguese catalogues exist and are waiting for contributors". src/postulo/locale/ holds 68 catalogues, machine-drafted and flagged draft until a speaker has read them.

8. `ci.yml`: the header says only `actions/checkout` is used

.forgejo/workflows/ci.yml:8-11 says "Only actions/checkout is used, and nothing else from any action marketplace". The same file uses actions/cache@v4 at :78 and :396 and actions/upload-artifact@v3 at :425. This comment is where a reviewer would check which third-party code runs in CI with the workflow's token, and it understates that list.

9. `docs/PLAN.md`: the extras, and the task queue

docs/PLAN.md:166 says extras: postgres, weasyprint, chromium. WeasyPrint is a default dependency (pyproject.toml:35, "weasyprint>=70"); the extras under [project.optional-dependencies] are postgres, chromium and server.
docs/PLAN.md:315-322 (assumption 3) says "still nothing enqueues a task" and that "#247 is where that happens, and the queue the Overview counts is structurally empty until it does". #247 is closed: core/errands.py:105 calls perform_errand.enqueue(errand.pk), and docker/compose.yml:88 defines a worker service behind the worker profile.

10. `docs/TRANSLATING.md`: the phase table

docs/TRANSLATING.md:19-27 still plans "0.4.0 | Asia and South America (#71) | Not started" and "0.5.0 | The rest of the world (#72) | Not started". #71 is closed, absorbed into #269, which orders languages by number of speakers rather than by continent; docs/PLAN.md:38 already states that rule. The Africa row puts #70 in 0.3.0, but #70 is open on the 1.0.0 milestone, and #72 is on 0.6.0.

Why it matters: people look for settings where the documentation says they are and copy commands from it, and contributors read these files to learn what the pipeline checks and what is planned. A page that is wrong in small ways stops being trusted in large ones.
Fix:
1. Point the three wiki pages to Settings → Accessibility, with the label the form uses, and add an Accessibility bullet to Getting started.
2. Describe the #264 logo handling in Tracking applications.
3. Drop tagged PDFs from Roadmap.
4. Use docker compose -f docker/compose.yml logs postulo in Troubleshooting.
5. Link Webhooks from The capture API and say that they carry no deletion event.
6. Delete the Scanning the image section and fold what it still says (why both scanners, why only fixable findings) into the earlier The image is scanned before it is pushed passage, which already says most of it. For a manual scan, point at ./scripts/scan-image.sh <image>.
7. Say that the catalogues are machine drafts waiting for a speaker to review them, and point at docs/TRANSLATING.md.
8. Name the three actions ci.yml uses in its header, with the reason each one is acceptable (both extra steps are already continue-on-error, and the upload step says why it stays on v3).
9. Write extras: postgres, chromium, server, and rewrite assumption 3 to say what is queued now and what the worker profile is for, or close the assumption.
10. Replace the per-continent table with the #269 rule, keeping only the rows that describe what has shipped.

Done when

A check in tests/test_wiki_surface.py that no wiki page says "Settings → Appearance" together with "Keyboard shortcuts" or "order number", and that none contains docker logs postulo. Both fail today.
A check, in tests/test_wiki_surface.py or a new tests/test_docs.py, that every action named by a uses: line in .forgejo/workflows/ci.yml is named in the file's header. It fails today for actions/cache and actions/upload-artifact.
CONTRIBUTING.md has one scanning section, which names scripts/scan-image.sh, and its Translations paragraph no longer names two languages.
docs/PLAN.md gives the real extras and the current state of the task queue, and docs/TRANSLATING.md describes the #269 ordering.
The remaining wiki points (sections 2, 3 and 5) are prose corrections.

Found on 2026-09-29 in a read-only review of postulo at 95348908d and the wiki at de1f52467, reading the user, contributor and planning documents against the settings, forms, compose file, workflows, `pyproject.toml` and the issue tracker. Checked again on 2026-10-01 against `main` at `0a5cad587`: still present. The code is now at `accounts/forms.py:450` (`AccessibilityForm`) and `:465` (the label), and `jobs/forms.py:142-146` (the upload's help text). In `CONTRIBUTING.md` the *Scanning the image* section is now at `:520-552` (its first sentence at `:522`), the two earlier passages at `:391` and `:418`, and the Translations paragraph at `:285-287`. In `.forgejo/workflows/ci.yml` the second `actions/cache@v4` is now at `:405` and `actions/upload-artifact@v3` at `:434`. Assumption 3 in `docs/PLAN.md` is now at `:328-335`. Eleven passages describe Postulo as it was before a change that has since landed. None is a defect in the code. Each sends somebody to a place that no longer exists, gives a command that fails, says something is missing that is there, or tells a contributor something false about what the build runs and what is planned; two of them contradict another section of the same file. Related to #281, #156 and #255, all closed. #281 moved two settings to *Settings → Accessibility* and #156 put the image scan in the pipeline, but the pages that described the earlier state were not all updated (sections 1 and 6); #255 revised `docs/PLAN.md`, and sections 8 and 9 slipped past that revision or were overtaken by #247. This issue lists what those three left behind, and the passages of the same kind left by #264, #235, #247 and #269. Paths in sections 1 to 5 are pages of the wiki; the rest are in the postulo repository. ## 1. Wiki: the accessibility choices are no longer under Appearance Since #281 the order number on career entries and the single-key shortcuts live on *Settings → Accessibility* (`core/settings_sections.py:44-51`; `accounts/forms.py:449`, `AccessibilityForm`, with `show_career_order`, `keyboard_shortcuts` and `nav_underline`). Three pages still send people to *Appearance*: - `Getting-started.md:38-41` describes them inside the *Appearance* bullet, and the list of sections has no *Accessibility* bullet at all. - `Capturing-postings.md:119` says "**Settings → Appearance → Keyboard shortcuts**". The setting is now under *Accessibility* and is labelled "Let a single key do something" (`accounts/forms.py:464`). - `Your-career-record.md:507-508` says "under *Settings → Appearance*". ## 2. Wiki: company logos accept SVG and keep their size `Tracking-applications.md:77-79` says "SVG is refused for now" and that whatever arrives is "re-encoded to a 256-pixel square". Since #264 an SVG is sanitised and kept as a vector, and a bitmap is re-encoded at its own size (`jobs/forms.py:141-145`, the upload's help text; `jobs/logos.py:16-22`). ## 3. Wiki: tagged PDFs are listed as still wanted `Roadmap.md:102-103` lists "Tagged PDFs" under *Still wanted, not scheduled* and links to *Accessibility → Known gaps*. `documents/pdf.py:83` renders `pdf/ua-1`, `Accessibility.md:187` says "They are tagged", and its *Known gaps* no longer mentions PDFs (#235). ## 4. Wiki: `docker logs postulo` names no container `Troubleshooting.md:17` says `docker logs postulo`. `docker/compose.yml:19` sets the project `name: postulo`, the service is `postulo` and there is no `container_name`, so the container is `postulo-postulo-1` and the command answers "No such container". Every other page uses `docker compose -f docker/compose.yml …`. ## 5. Wiki: outbound webhooks are described as not built `The-capture-API.md:295-297` says outbound webhooks "are a separate feature and not built yet". `Webhooks.md` documents them. Its event table has no deletion event, so the paragraph's point (a mirror must notice absences itself) still stands; only the reason given is wrong. ## 6. `CONTRIBUTING.md`: "Scanning the image" says nothing scans the image `CONTRIBUTING.md:518-550`. Line 520 says "Nothing scans the image yet — that needs a runner that can build one, and is #156", and gives two manual commands that run unpinned scanner images (`aquasec/trivy`, `anchore/grype`) against `postulo:latest`. About a hundred lines earlier, `:389` and `:416` say that `scripts/scan-image.sh` scans both the dev image and the release image before they are pushed, and `.forgejo/workflows/image.yml:127` and `.forgejo/workflows/dev-image.yml:126` call it. #156 is closed. The script pins `aquasec/trivy:0.74.0` and `anchore/grype:v0.100.0` (`scripts/scan-image.sh:58`, `:62`) and records why the pin matters. A reader who lands on this section first concludes that there is no gate, and anyone who follows its commands runs whatever scanner image is current, which the script's own comments explain is unreliable. ## 7. `CONTRIBUTING.md`: the Translations paragraph `CONTRIBUTING.md:283-285` says "French and Portuguese catalogues exist and are waiting for contributors". `src/postulo/locale/` holds 68 catalogues, machine-drafted and flagged `draft` until a speaker has read them. ## 8. `ci.yml`: the header says only `actions/checkout` is used `.forgejo/workflows/ci.yml:8-11` says "Only `actions/checkout` is used, and nothing else from any action marketplace". The same file uses `actions/cache@v4` at `:78` and `:396` and `actions/upload-artifact@v3` at `:425`. This comment is where a reviewer would check which third-party code runs in CI with the workflow's token, and it understates that list. ## 9. `docs/PLAN.md`: the extras, and the task queue - `docs/PLAN.md:166` says `extras: postgres, weasyprint, chromium`. WeasyPrint is a default dependency (`pyproject.toml:35`, `"weasyprint>=70"`); the extras under `[project.optional-dependencies]` are `postgres`, `chromium` and `server`. - `docs/PLAN.md:315-322` (assumption 3) says "still nothing enqueues a task" and that "#247 is where that happens, and the queue the Overview counts is structurally empty until it does". #247 is closed: `core/errands.py:105` calls `perform_errand.enqueue(errand.pk)`, and `docker/compose.yml:88` defines a `worker` service behind the `worker` profile. ## 10. `docs/TRANSLATING.md`: the phase table `docs/TRANSLATING.md:19-27` still plans "0.4.0 | Asia and South America (#71) | Not started" and "0.5.0 | The rest of the world (#72) | Not started". #71 is closed, absorbed into #269, which orders languages by number of speakers rather than by continent; `docs/PLAN.md:38` already states that rule. The Africa row puts #70 in 0.3.0, but #70 is open on the 1.0.0 milestone, and #72 is on 0.6.0. - **Why it matters:** people look for settings where the documentation says they are and copy commands from it, and contributors read these files to learn what the pipeline checks and what is planned. A page that is wrong in small ways stops being trusted in large ones. - **Fix:** 1. Point the three wiki pages to *Settings → Accessibility*, with the label the form uses, and add an *Accessibility* bullet to *Getting started*. 2. Describe the #264 logo handling in *Tracking applications*. 3. Drop tagged PDFs from *Roadmap*. 4. Use `docker compose -f docker/compose.yml logs postulo` in *Troubleshooting*. 5. Link *Webhooks* from *The capture API* and say that they carry no deletion event. 6. Delete the *Scanning the image* section and fold what it still says (why both scanners, why only fixable findings) into the earlier *The image is scanned before it is pushed* passage, which already says most of it. For a manual scan, point at `./scripts/scan-image.sh <image>`. 7. Say that the catalogues are machine drafts waiting for a speaker to review them, and point at `docs/TRANSLATING.md`. 8. Name the three actions `ci.yml` uses in its header, with the reason each one is acceptable (both extra steps are already `continue-on-error`, and the upload step says why it stays on v3). 9. Write `extras: postgres, chromium, server`, and rewrite assumption 3 to say what is queued now and what the `worker` profile is for, or close the assumption. 10. Replace the per-continent table with the #269 rule, keeping only the rows that describe what has shipped. ## Done when - A check in `tests/test_wiki_surface.py` that no wiki page says "Settings → Appearance" together with "Keyboard shortcuts" or "order number", and that none contains `docker logs postulo`. Both fail today. - A check, in `tests/test_wiki_surface.py` or a new `tests/test_docs.py`, that every action named by a `uses:` line in `.forgejo/workflows/ci.yml` is named in the file's header. It fails today for `actions/cache` and `actions/upload-artifact`. - `CONTRIBUTING.md` has one scanning section, which names `scripts/scan-image.sh`, and its Translations paragraph no longer names two languages. - `docs/PLAN.md` gives the real extras and the current state of the task queue, and `docs/TRANSLATING.md` describes the #269 ordering. - The remaining wiki points (sections 2, 3 and 5) are prose corrections.

tiagoagueda added this to the 0.6.0 milestone

2026-10-01 10:46:28 +00:00

tiagoagueda added the

documentation

tier

labels

2026-10-01 10:46:28 +00:00

tiagoagueda self-assigned this

2026-10-11 10:57:32 +00:00

tiagoagueda referenced this issue from a commit

2026-10-12 07:13:09 +00:00

Point the pages at where things are now, and keep three of them honest