refactor: strip WP-/RB- ticket refs from backend (RD-19)
The backend half of the sweep RD-18 did for the front end. 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. public/letter.css and LetterHtml.golden.html change together, because the renderer inlines the CSS and the golden file snapshots the result. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,149 @@
|
||||
# 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. **Nothing in `backend/` is exempt. Strip all 370.** Unlike the front end, 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.
|
||||
|
||||
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 0
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -113,7 +113,7 @@ two. Note that RD-15 exists because 22 abandoned agent worktrees are still on di
|
||||
| RD-16 | ~~`parseDashboardView` returns `BigProfile`~~ — DROPPED, see PLAN.md 2.2 | 01 | | n/a |
|
||||
| RD-17 | `successOf`/`successOr` sweep — 10 sites, 8 files | 01 | | done |
|
||||
| RD-18 | Ticket-reference sweep, frontend — 181 refs, 100 files | 01 | yes | done |
|
||||
| RD-19 | Ticket-reference sweep, backend — 370 refs, 86 files | 01 | | todo |
|
||||
| RD-19 | Ticket-reference sweep, backend — 370 refs, 86 files | 01 | | done |
|
||||
| RD-20 | `wizard-errors.ts` + spec, adopted by all 3 wizards | 02 | | todo |
|
||||
| RD-21 | `rich-text-dom.ts` helpers + spec cases | 02 | yes | todo |
|
||||
| RD-22 | `intake-wizard` to 3 step components | 08, 20 | yes | todo |
|
||||
|
||||
Reference in New Issue
Block a user