ehoandClaude Opus 5
12f17d9d73
Two backlog trees are complete: `docs/project/backlog/` (75 files, every WP done) and `docs/project/refactor-backlog-setup/` (the arc before it). Move both under `docs/project/archive/` with `git mv`, so history stays intact through `git log --follow`. `SHOWCASE-ROADMAP.md` moves with them, because it points at the now-archived backlog README. Add `docs/project/archive/README.md`. It states that these trees are historical and names the two directories that are still live. Repoint every inbound reference named in RD-30's Files table: CLAUDE.md, the root README, both backend READMEs, `LetterHtml.cs`, `a11y.mdx`, the `document-feature` and `new-ssp` skills, and the readable-codebase PLAN, README, and RD-19 ticket. Fix two upward-relative links inside the moved WP files (WP-68, WP-69) that gained a directory level and would otherwise break. Repoint `.prettierignore`'s two agent-prompt exclusions to their new path, so prettier keeps leaving those files' exact wording alone. Mark RD-30 done and check off its acceptance criteria; flip its README row to done. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
169 lines
8.1 KiB
Markdown
169 lines
8.1 KiB
Markdown
# RD-19 — Strip the `WP-`/`RB-` ticket references from `backend/`
|
|
|
|
Status: done
|
|
Source: PLAN.md Phase 2, item 4
|
|
|
|
## Why
|
|
|
|
The backend half of the sweep RD-18 did for the front end. 370 `WP-NN`/`RB-NN` references sit
|
|
in comments across 86 files under `backend/` — 70 `.cs` files plus the Dockerfile, four shell
|
|
scripts, four compose files, two `README.md`s and a handful of config files. `git blame` holds
|
|
the provenance and stays correct when the code moves; the comment names a closed ticket and
|
|
tells the reader nothing the sentence around it does not.
|
|
|
|
Strip the reference, keep the sentence. No behaviour changes.
|
|
|
|
## Read first
|
|
|
|
- `backend/tests/BigRegister.Tests/LetterHtmlTests.cs:8-13` — the golden-file test, and the
|
|
reason decision 2 exists.
|
|
- `public/letter.css` lines 1 and 4 — three references, mirrored byte for byte inside the
|
|
golden file.
|
|
- `backend/src/BigRegister.Api/appsettings.json:9` — the `_Zgw` key, a documentation string
|
|
rather than a comment.
|
|
- `RD-18`'s decisions block, for the sentence-quality rule this ticket repeats.
|
|
|
|
## Decisions (pre-made, don't relitigate)
|
|
|
|
1. **Strip all 370 except two.** No backend file disables a check by naming the ticket that
|
|
removes it — verified against `pragma warning disable`, `Skip =`, `NoWarn` and
|
|
`SuppressMessage`, none of which carries a reference. Keep all 40 `ADR-000x` references; that
|
|
count must not move.
|
|
|
|
**Corrected after the ticket ran.** The original text said "nothing is exempt", and it was
|
|
wrong. Two references are part of a path to a document that still exists:
|
|
|
|
| Site | Reference |
|
|
| ---------------------------------- | ----------------------------------------------------------- |
|
|
| `backend/README.md:18` | `docs/project/archive/backlog/WP-22-durable-persistence.md` |
|
|
| `Domain/Letters/LetterHtml.cs:153` | `docs/project/archive/backlog/WP-25-letter-preview-html.md` |
|
|
|
|
RD-18 exempted this same class of reference (`a11y.mdx:68`). A path that resolves is a
|
|
pointer, not provenance. Stripping the number breaks the path, and describing the file in
|
|
prose instead makes the reader search for it.
|
|
|
|
2. **`public/letter.css` and `LetterHtml.golden.html` change together, or the build goes red.**
|
|
`LetterHtml.cs:161` finds `public/letter.css` at run time and **inlines it** into the
|
|
rendered letter. `LetterHtml.golden.html` is a snapshot of that output, so it embeds the
|
|
same CSS comment verbatim. Both hold the same three references (WP-24, WP-25 on line 1;
|
|
WP-25 on line 4).
|
|
|
|
- Edit `public/letter.css`.
|
|
- Apply the identical edit to the copy inside `LetterHtml.golden.html`.
|
|
- Editing either one alone fails `Renders_the_golden_brief`.
|
|
|
|
`public/letter.css` is the one file outside `backend/` that this ticket touches, exactly as
|
|
`scripts/gen-behaviour-spec.mjs` was for RD-18.
|
|
|
|
3. **No spec regeneration is needed, and that is a fact about C#, not an oversight.**
|
|
`scripts/gen-behaviour-spec.mjs:124` extracts backend `[Fact]`/`[Theory]` **method names**
|
|
into `behaviour-spec.mdx`. A C# method name cannot contain a hyphen, so no backend test name
|
|
can carry a `WP-NN`. Verified: zero `WP_NN`/`RB_NN` underscore variants exist either. Do not
|
|
run `gen:behaviour-spec`. If the drift check fires, you changed something this ticket did not
|
|
intend.
|
|
|
|
4. **Three kinds of reference live in a string, not a comment. All three are display-only and
|
|
all three get stripped:**
|
|
|
|
| Site | What it is |
|
|
| ---------------------------------------------------------------------------------------- | -------------------------------------------- |
|
|
| `appsettings.json:9`, the `_Zgw` key | a documentation string; no code binds `_Zgw` |
|
|
| `setup_configuration/data.yaml:15,29` + `.template` | the OpenZaak harness's `name:` / `label:` |
|
|
| `bootstrap-notificaties.sh:44`, `verify-notificatie.sh:32`, `bootstrap-catalogus.sh:171` | a `label=` value and two `echo` lines |
|
|
|
|
Verified: nothing in the repository greps for these labels, so renaming them breaks no
|
|
script. They are read by humans looking at an OpenZaak admin page.
|
|
|
|
5. **Keep the sentence readable, not merely shorter** — the same rule as RD-18. Several `.cs`
|
|
XML doc comments read "… (WP-53) is the acting citizen" or "— WP-73: a freshly submitted
|
|
aanvraag …", where the reference sits mid-sentence. Rewrite the clause. A stripped line must
|
|
not leave an empty `()`, a stranded "see", a dangling dash, or a doubled space.
|
|
|
|
6. **Leave `<paramref>`, `<see cref=…>` and every other XML doc tag intact.** They are compiled
|
|
references; breaking one is a build warning at best and a silent documentation hole at worst.
|
|
Only the ticket number inside the prose goes.
|
|
|
|
## Files
|
|
|
|
Everything under `backend/`, plus `public/letter.css`. About 87 files change.
|
|
|
|
As in RD-18, this ticket's acceptance commands address the directory rather than a file list,
|
|
because the sweep's contract is "no reference survives".
|
|
|
|
## Steps
|
|
|
|
1. Strip the references in `backend/`, working directory by directory so the diff stays
|
|
reviewable.
|
|
2. Apply decision 2: edit `public/letter.css`, then make the golden file's embedded copy match
|
|
it exactly.
|
|
3. Run `cd backend && dotnet test` on its own before the full gate. It is the fastest proof
|
|
that step 2 landed correctly.
|
|
4. `git add -A`, then run the acceptance commands.
|
|
5. Update this ticket's `Status:` to `done` and the README's RD-19 row to `done`.
|
|
6. Commit all of it together.
|
|
|
|
## Acceptance criteria
|
|
|
|
Measured against the tree before handover. `git grep -o … | wc -l` counts **occurrences**;
|
|
`git grep -c` counts lines and would give a different, wrong number.
|
|
|
|
```bash
|
|
git grep -oE "\b(WP|RB)-[0-9]+" -- backend public/letter.css | wc -l # is 373 -> MUST be 2
|
|
```
|
|
|
|
The two survivors are the document paths in decision 1:
|
|
|
|
```bash
|
|
git grep -oE "\b(WP|RB)-[0-9]+" -- backend/README.md \
|
|
backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs | wc -l # MUST be 2
|
|
```
|
|
|
|
The ADR references survive, and the sweep leaves no damaged prose:
|
|
|
|
```bash
|
|
git grep -oE "ADR-[0-9]+" -- backend | wc -l # unchanged: 40
|
|
git grep -nE "^\s*(//|\*|#).*\s\(\)" -- backend public/letter.css | wc -l # unchanged: 0
|
|
git grep -nE "^\s*(//|\*|#).*[a-z] [a-z]" -- backend public/letter.css | wc -l # unchanged: 0
|
|
```
|
|
|
|
The golden file still matches the renderer (decision 2):
|
|
|
|
```bash
|
|
cd backend && dotnet test --filter FullyQualifiedName~LetterHtmlTests # exits 0
|
|
```
|
|
|
|
```bash
|
|
npm run ci # exits 0
|
|
```
|
|
|
|
## Verification
|
|
|
|
`npm run ci` is enough. `--full` is **not** required: this ticket touches no story, no `.mdx`,
|
|
and nothing under `libs/shared/src/ui/`. The README's Order table already leaves that column
|
|
blank for RD-19, and it is right this time.
|
|
|
|
If `dotnet test` fails with `SQLite Error 1: 'no such table: …'`, that is the stale-database
|
|
trap, not your change. See this README's Troubleshooting section.
|
|
|
|
## Out of scope
|
|
|
|
- `apps/`, `libs/`, `docs/`, `.claude/`, `e2e/` — RD-18 did the first two; the rest keep their
|
|
references.
|
|
- `public/` beyond `letter.css`.
|
|
- Rewording a comment beyond what removing the reference requires.
|
|
- The `Case`/`Zaak` vocabulary rename (PLAN, "Deliberately out of scope").
|
|
|
|
## Risks
|
|
|
|
- **The golden file is the trap in this ticket.** Three references in `public/letter.css` are
|
|
mirrored inside `LetterHtml.golden.html`. Change one without the other and the golden test
|
|
fails. Change neither and the acceptance count cannot reach 0.
|
|
- **A reference inside a string is still a reference.** Decision 4 lists all three kinds. They
|
|
do not look like comments, so a comment-only regular expression misses them and the count
|
|
stops short of 0.
|
|
- **Do not touch `<see cref=…>` or `<paramref name=…>`** (decision 6).
|
|
- **`git grep`, never `grep -r`.** `grep -r` reaches `backend/bin`, `backend/obj` and the
|
|
gitignored SQLite files.
|
|
- **370 is measured today.** If your first count differs, re-measure before assuming the ticket
|
|
is stale.
|