Record what you sent: one-off letters and superseded files are offered, though the help texts and wiki say not #510

New issue

Closed

opened 2026-10-01 10:47:12 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-01 10:47:12 +00:00

Owner

Found on 2026-09-29 in a read-only review of postulo at 95348908d, following the reusable template flag and the supersedes link from the forms that set them to the form that reads them.

Checked again on 2026-10-01 against main at 0a5cad587: still present. The code is now at documents/models.py:418-422 (is_template and its help text); documents/forms.py and the letter list's template have not moved.

Two promises made where a person sets something up are not kept where it is used. A letter's reusable template box says templates are what is offered when sending, and the wiki says to untick it for a one-off letter; an upload's supersedes field says the older version is "kept but no longer offered". SendDocumentsForm filters on neither, so every letter and every version of every file is offered.

Where: documents/forms.py:320-326, SendDocumentsForm.__init__, which sets CoverLetter.objects.for_user(user) and UploadedDocument.objects.for_user(user) with no further filter; the promises are at documents/models.py:378-382 (is_template, help text "Templates appear when you send a letter with an application."), documents/forms.py:247 (replaces, "An older version of the same thing, kept but no longer offered.") and the wiki's Cover letters page, section Templates ("Letters marked reusable template are offered when you record what you sent with an application. Untick it for a one-off letter written for a single employer.").
What happens: a person keeps a one-off letter written for employer A with the box unticked, and has uploaded CV (v2) superseding CV (v1). On Record what you sent for employer B, the letter picker lists the one-off letter beside the templates and the file list offers CV (v1) beside CV (v2). Across src, tests and templates, is_template is read only by the letter list's badge (templates/documents/letter_list.html:46), the API, the export, the admin and the demo seed; nothing narrows a choice by it, and nothing narrows uploads by replaced_by.
Why it matters: the flag does nothing a person can see beyond a badge, so unticking it gives a false sense of having tidied the picker, and the lists grow with every one-off letter and every superseded version. Picking the wrong one records, as sent, a document the person had set aside.
Fix: in SendDocumentsForm.__init__, narrow cover_letter to is_template=True and uploads to replaced_by__isnull=True. Recording something sent in the past with an old version must stay possible, so either keep a bound value that falls outside the filter (re-rendering a form with errors must not drop it) or offer the older items under a "show all" choice. If the maintainer prefers to keep everything selectable, change the two help texts and the wiki instead, so they describe what the flag and the supersedes link actually do.

Done when

Tests in tests/test_documents.py assert that the Record what you sent form offers neither a letter with is_template=False nor an upload that another upload replaces (or, if the texts are changed instead, that the help texts no longer promise it).

Found on 2026-09-29 in a read-only review of postulo at 95348908d, following the *reusable template* flag and the *supersedes* link from the forms that set them to the form that reads them. Checked again on 2026-10-01 against `main` at `0a5cad587`: still present. The code is now at `documents/models.py:418-422` (`is_template` and its help text); `documents/forms.py` and the letter list's template have not moved. Two promises made where a person sets something up are not kept where it is used. A letter's *reusable template* box says templates are what is offered when sending, and the wiki says to untick it for a one-off letter; an upload's *supersedes* field says the older version is "kept but no longer offered". `SendDocumentsForm` filters on neither, so every letter and every version of every file is offered. - **Where:** `documents/forms.py:320-326`, `SendDocumentsForm.__init__`, which sets `CoverLetter.objects.for_user(user)` and `UploadedDocument.objects.for_user(user)` with no further filter; the promises are at `documents/models.py:378-382` (`is_template`, help text "Templates appear when you send a letter with an application."), `documents/forms.py:247` (`replaces`, "An older version of the same thing, kept but no longer offered.") and the wiki's *Cover letters* page, section *Templates* ("Letters marked **reusable template** are offered when you record what you sent with an application. Untick it for a one-off letter written for a single employer."). - **What happens:** a person keeps a one-off letter written for employer A with the box unticked, and has uploaded *CV (v2)* superseding *CV (v1)*. On *Record what you sent* for employer B, the letter picker lists the one-off letter beside the templates and the file list offers *CV (v1)* beside *CV (v2)*. Across `src`, `tests` and `templates`, `is_template` is read only by the letter list's badge (`templates/documents/letter_list.html:46`), the API, the export, the admin and the demo seed; nothing narrows a choice by it, and nothing narrows uploads by `replaced_by`. - **Why it matters:** the flag does nothing a person can see beyond a badge, so unticking it gives a false sense of having tidied the picker, and the lists grow with every one-off letter and every superseded version. Picking the wrong one records, as sent, a document the person had set aside. - **Fix:** in `SendDocumentsForm.__init__`, narrow `cover_letter` to `is_template=True` and `uploads` to `replaced_by__isnull=True`. Recording something sent in the past with an old version must stay possible, so either keep a bound value that falls outside the filter (re-rendering a form with errors must not drop it) or offer the older items under a "show all" choice. If the maintainer prefers to keep everything selectable, change the two help texts and the wiki instead, so they describe what the flag and the supersedes link actually do. ## Done when - Tests in `tests/test_documents.py` assert that the *Record what you sent* form offers neither a letter with `is_template=False` nor an upload that another upload `replaces` (or, if the texts are changed instead, that the help texts no longer promise it).

tiagoagueda added this to the 0.6.0 milestone

2026-10-01 10:47:12 +00:00

tiagoagueda added the

interface

tier

bug

labels

2026-10-01 10:47:12 +00:00

tiagoagueda referenced this issue from a commit

2026-10-04 04:15:10 +00:00

Offer only templates and current files when recording what was sent

tiagoagueda closed this issue