From 8642d64c3abb35818dd89a7fb47738bf9939a043 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Fri, 4 Sep 2026 08:35:53 +0200 Subject: [PATCH] =?UTF-8?q?docs(wa):=20WA006=20=E2=80=94=20English=20is=20?= =?UTF-8?q?the=20working=20language,=20French=20documentation=20is=20a=20p?= =?UTF-8?q?roduct?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WA001 settled the language of `documentation/`, the ADRs and the Cursor rules, and said nothing about everything else the project writes. The gap filled itself with French: pull request titles and bodies, issue and review comments, commit messages, prise files, journal entries. That held while one person read the repository. It stopped holding when the work became public: a contributor cannot review a change whose justification they cannot read — and the justification is the part that carries the weight here, because this project routinely writes down *why* a fix takes the shape it takes. The cross-review of 3 September produced findings whose entire value was in their argument, and every argument was in French. WA006 therefore names English as the working language across every surface — pull requests, issues, comments, reviews, commit messages, prise files, journal entries, code identifiers, release notes — and names the single exception precisely: the `*.fr.md` translations of the user documentation are a **product for readers**, not a working language. They stay, and they stay in parity. The line that decides any future case is written into the agreement rather than left to be guessed: text addressed to a *user* of Durable follows the product; text addressed to whoever *works* on Durable is English. Two things the agreement deliberately does not do. It does not rewrite history — the value of a readable log does not survive invalidating every commit reference in every issue, ADR and journal entry that cites one. And it is not a mandate to bulk-translate: existing French text in scope is listed as debt so that it is visible rather than silent — `documentation/audit/` (22 files, landed by #271 and unknown to the three maps), `documentation/journal/inbox/` (8 entries, in a directory WA001 already required to be English), and the prise files. The pull requests, issues and comments dated 3 September and later were translated on 4 September, before this was written. They are the starting point, not part of the debt. No CI guard, and that is a choice: the rule is worth stating before it is worth automating. Co-Authored-By: Claude Opus 5 (1M context) --- documentation/INDEX.md | 1 + .../WA006-english-is-the-working-language.md | 101 ++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 documentation/wa/WA006-english-is-the-working-language.md diff --git a/documentation/INDEX.md b/documentation/INDEX.md index 5c083fba..306ae195 100644 --- a/documentation/INDEX.md +++ b/documentation/INDEX.md @@ -76,6 +76,7 @@ This repository documents the **Durable** component (durable execution orchestra | WA003 | GitHub epics, tasks, and project tracking | [wa/WA003-github-epics-tasks-and-project-tracking.md](wa/WA003-github-epics-tasks-and-project-tracking.md) | | WA004 | MIT license for the repository and Composer packages | [wa/WA004-mit-license-distribution.md](wa/WA004-mit-license-distribution.md) | | WA005 | The canvas is the source, `layouts/index.html` is output | [wa/WA005-the-canvas-is-the-source-the-page-is-output.md](wa/WA005-the-canvas-is-the-source-the-page-is-output.md) | +| WA006 | English is the working language; French documentation is a product | [wa/WA006-english-is-the-working-language.md](wa/WA006-english-is-the-working-language.md) | ## Opportunity solution trees (OST) diff --git a/documentation/wa/WA006-english-is-the-working-language.md b/documentation/wa/WA006-english-is-the-working-language.md new file mode 100644 index 00000000..04ae3e01 --- /dev/null +++ b/documentation/wa/WA006-english-is-the-working-language.md @@ -0,0 +1,101 @@ +# WA006 — English is the working language; French documentation is a product + +## Status + +Accepted — 4 September 2026. Widens [WA001](WA001-english-language-documentation.md), which stays in force. + +## Context + +WA001 settled the language of `documentation/`, `.cursor/rules/` and the ADRs. It said nothing about +everything else the project writes, and the gap filled itself with French: pull request titles and +bodies, issue and review comments, commit messages, prise files, journal entries. + +That was tenable while the repository was read by one person. It stopped being tenable the moment +the work became public. **A contributor who lands on a pull request cannot review a change whose +justification they cannot read** — and the justification is the part that matters here, because this +project routinely writes down *why* a fix takes the shape it takes. On 3 September 2026 a +cross-review of the seven open pull requests produced findings whose value was entirely in their +argument; every one of those arguments was in French. + +There is also a second, quieter cost. The repository already contains English documentation that +cites French artefacts — an `UPGRADE.md` note pointing at a French pull request, an ADR referencing a +French journal entry. A reader following those links leaves the language they were reading in, +mid-sentence. + +## Agreement + +**English is the working language of this project.** It applies to everything the project writes, +whether it lives in the repository or on GitHub: + +| Surface | Language | +|---|---| +| Pull request titles and bodies | English | +| Issue titles and bodies | English | +| Comments — on issues, on pull requests, inline review comments | English | +| Review summaries and approvals | English | +| Commit messages, including trailers | English | +| Prise files under `.worktrees/prises/` | English | +| Journal entries under `documentation/journal/` | English (already required by WA001) | +| ADRs, WAs, OSTs, PRDs, OpenSpec changes | English (already required by WA001) | +| Code identifiers, docblocks, comments in `src/` and `tests/` | English | +| Release notes and tags | English | + +### The one exception + +**The French translations of the user documentation.** The `*.fr.md` files under +`documentation/user/`, and the French canvases and layouts that render them, are **a product for +readers** — not a working language. They stay French, they stay maintained in parity with their +English counterpart, and nothing in this agreement invites translating them away. + +The distinction that decides any future case is this: *is this text addressed to a user of Durable, +in a language we chose to serve them in?* If yes, it follows the product. If it is addressed to +whoever works on Durable — a reviewer, a maintainer, our future selves — it is English. + +Two consequences worth stating, because they are the cases that will come up: + +- A **French user page has an English source of record.** When the two disagree, the English page is + the one that is right, and the French one is a bug to fix — that is what parity means. +- **Third-party quotations** stay in their original language, as WA001 already allows. + +## What this does not do + +**It does not rewrite history.** Commit messages already written stay as they are: rewriting them +would mean rewriting every merged branch, and the value of a readable log does not survive +invalidating every commit reference in every issue, ADR and journal entry that cites one. + +**It is not a mandate to bulk-translate.** Existing French text in scope is debt, and it is listed +below so that it is visible rather than silent. It gets translated when the file is next edited for +another reason, or in a change that says so. + +### Known debt, on the day this was written + +| Where | Extent | +|---|---| +| `documentation/audit/` | 22 files, French, landed by #271 — and unknown to `INDEX.md`, `LIFECYCLE.md` and `HUGO.md` | +| `documentation/journal/inbox/` | 8 entries, French, in a directory WA001 already required to be English | +| `.worktrees/prises/` | 18 open prise files — 17 French, plus this branch's, which is not — and `PRISES.md` itself | +| Commit history | French throughout; frozen by the paragraph above | + +The pull requests, issues and comments dated 3 September 2026 and later were translated on +4 September 2026, before this agreement was written. They are the starting point, not part of the +debt. + +## Consequences + +- Reviews may reject a non-English addition to any surface in the table above, the same way WA001 + allows it for documentation. +- An agent working on this repository writes English by default, and asks before writing anything + else. The single exception is narrow enough to name explicitly when it applies. +- `documentation/audit/` is the first thing this agreement judges, and it judges it + non-conforming — in language and in placement. Deciding what happens to it is a follow-up, not a + silent grandfathering. +- Nothing here is enforced by CI today. A guard is possible — a check on the language of a pull + request body, or on new files under the paths above — and it is deliberately not part of this + agreement: the rule is worth stating before it is worth automating, and WA005 is the reminder that + an unenforced rule is still a rule people can follow. + +## References + +- [WA001 — English language for project documentation](WA001-english-language-documentation.md) +- [documentation/LIFECYCLE.md](../LIFECYCLE.md) +- [documentation/INDEX.md](../INDEX.md)