[Bug] PR template lists 8 languages instead of 32, and never asks about the trade-off #510

New issue

Closed

opened 2026-07-22 09:06:44 +00:00 by brenno · 0 comments

brenno commented

2026-07-22 09:06:44 +00:00

Owner

Problem / motivation

Two problems with .github/PULL_REQUEST_TEMPLATE.md, one factual and one
structural.

1. The translation checklist names 8 languages; there are 32.

Lines 15-16 ask the contributor to confirm that new UI strings are translated in
"every supported language (nl/en/it/de/fr/es/fy/pap)". Counting
AppLocalizations.languageNames on main gives 32 entries. A contributor who
ticks that box honestly is 24 languages short and has no way to know it. The
checklist is actively misleading rather than merely incomplete.

2. Nothing in the template asks the contributor to weigh the project's
principles.

The gates in make check cover what can be mechanised: round-trip fidelity of
the Markdown, the network guards, licences, coverage, the SBOM, accessibility
labels and contrast, the size and method-length ratchets. What they cannot cover
is the judgement — whether a change quietly makes the user's decks less portable,
introduces a party that has to be trusted, or writes a promise into the UI that
the code does not keep.

That weighing exists as a working agreement for maintainers, but the template is
the only place an outside contributor ever sees. Interoperability and
sovereignty rarely break with a bang; they erode one convenient exception at a
time, and a green make check does not see it.

Proposed solution

Replace the parenthesised language list with a pointer to the actual source of
truth (AppLocalizations.languageNames) and to make add-l10n, so the
template cannot go stale again the next time a language is added. A hardcoded
count is what broke here; do not replace it with a fresh hardcoded count.
Add one checklist item along the lines of: "If this change touches the file
format, storage, a dependency, outgoing network traffic, or a promise made in
the UI or docs — I described the trade-off in the summary: which principle I
gave precedence, why, and what would change my mind."
Keep it to a single item. A checklist that fires on every PR becomes a box
people tick without reading, which guards nothing.

Marp / file-format impact

None; this is contributor-facing documentation.

Alternatives considered

A CI check that compares the template's language list against
languageNames — rejected: it fixes the smaller of the two problems and there
is no runner on this Forgejo instance anyway. Pointing at the source of truth
removes the class of error instead.

Note that the second point is deliberately not mechanisable. It is a prompt for
a human judgement, and the value is in the sentence the contributor writes, not
in the tick.

**Problem / motivation** Two problems with `.github/PULL_REQUEST_TEMPLATE.md`, one factual and one structural. **1. The translation checklist names 8 languages; there are 32.** Lines 15-16 ask the contributor to confirm that new UI strings are translated in "every supported language (nl/en/it/de/fr/es/fy/pap)". Counting `AppLocalizations.languageNames` on `main` gives 32 entries. A contributor who ticks that box honestly is 24 languages short and has no way to know it. The checklist is actively misleading rather than merely incomplete. **2. Nothing in the template asks the contributor to weigh the project's principles.** The gates in `make check` cover what can be mechanised: round-trip fidelity of the Markdown, the network guards, licences, coverage, the SBOM, accessibility labels and contrast, the size and method-length ratchets. What they cannot cover is the judgement — whether a change quietly makes the user's decks less portable, introduces a party that has to be trusted, or writes a promise into the UI that the code does not keep. That weighing exists as a working agreement for maintainers, but the template is the only place an outside contributor ever sees. Interoperability and sovereignty rarely break with a bang; they erode one convenient exception at a time, and a green `make check` does not see it. **Proposed solution** - Replace the parenthesised language list with a pointer to the actual source of truth (`AppLocalizations.languageNames`) and to `make add-l10n`, so the template cannot go stale again the next time a language is added. A hardcoded count is what broke here; do not replace it with a fresh hardcoded count. - Add one checklist item along the lines of: *"If this change touches the file format, storage, a dependency, outgoing network traffic, or a promise made in the UI or docs — I described the trade-off in the summary: which principle I gave precedence, why, and what would change my mind."* - Keep it to a single item. A checklist that fires on every PR becomes a box people tick without reading, which guards nothing. **Marp / file-format impact** None; this is contributor-facing documentation. **Alternatives considered** A CI check that compares the template's language list against `languageNames` — rejected: it fixes the smaller of the two problems and there is no runner on this Forgejo instance anyway. Pointing at the source of truth removes the class of error instead. Note that the second point is deliberately not mechanisable. It is a prompt for a human judgement, and the value is in the sentence the contributor writes, not in the tick.

brenno added the

accepted

docs

bug

labels

2026-07-22 09:06:44 +00:00

brenno referenced this issue from a pull request that will close it,

2026-07-22 10:17:17 +00:00

docs: PR-sjabloon wijst naar de bron van waarheid en vraagt naar de afweging #524

brenno referenced this issue from a commit

2026-07-22 10:17:18 +00:00

docs(sjabloon): wijs naar de bron van waarheid, en vraag naar de afweging