docs: release prep for v1.42.0 (changelog and documentation sweep)

[vavallee]

Summary

Release prep for v1.42.0: a documentation sweep for everything merged since v1.41.0 (two docs: commits) and the CHANGELOG assembly (last commit, chore(release)), rebased onto main at 671576b3 (#3185). No tag, no GitHub release, not merged: the maintainer tags and decides the final number.

The release now includes the whole audit series (#3174, #3176, #3175, #3177, #3185, #3187), #3171 (cover upload) and #3173. The audit findings doc (#3188) merged while I worked and the branch is rebased onto it (main d25ac8e8); docs/audits/2026-10-bindery-security-errors-performance.md exists, so the CHANGELOG and ROADMAP references resolve.

Version: v1.42.0

Per the SemVer table in the tag-release skill: new features, new endpoints and new settings values are a minor bump. Merged since v1.41.0 and user visible (plus the audit's API status changes and 90 day download retention): BnF as an opt in primary provider, book ratings in the UI, Add to Library Books / Authors filter and author work counts, covers taken from a book's own file, Norwegian and Swedish translations, fixing one book's series (migration 102), books in library per author. Nothing removed or renamed, no env var changed, so no major. The maintainer decides the final number.

Inventory (merged since v1.41.0, bot and deploy PRs excluded)

Docs gate: Y = the PR touched the docs the gate table names, N/A = no user visible or documented surface changed, GAP = surface changed and docs lagged (fixed by commit 1).

PR	Author	Issue (reporter)	Fragment	Docs gate
#3131 Go 1.26.9	francisrath	none	go-1.26.9	Y (ARCHITECTURE)
#3088 author page sort and filters	johnistheman	#3087, refs #3086 (johnistheman)	3087	GAP, fixed
#2699 Hardcover daily quota hold	magrhino	#2593 (magrhino)	2593	Y (DEPLOYMENT)
#2915 split editions counted as covered	gchahcg	#2524 (magrhino)	2524	Y (Hardcover wiki)
#3082 compact selects on touch	johnistheman	#3081 (johnistheman)	3081	N/A
#3138 decomposed accents in release titles	francisrath	#3137 (francisrath)	3137	Y (search-design)
#3140 multi-disc torrent folder placed whole	francisrath	#3139 (francisrath)	3139	Y (Storage wiki)
#3127 Add to Library Books / Authors filter	johnistheman	#3126 (johnistheman)	3126	Y (User guide); API count note added
#3094 cover from a book's own file	francisrath	#2980 (francisrath)	2980	Y (README, User guide)
#2994 Norwegian and Swedish	vavallee	#2985 (vavallee)	2985	Y (README)
#3093 no translation cover by ISBN	francisrath	#3018 (francisrath)	3018	N/A
#3116 last name author sort	francisrath	#2805 (vavallee)	2805	GAP, fixed
#3136 scan skips junk folders	francisrath	#3135 (francisrath)	3135	Y (User guide, Storage wiki)
#3155 NAS thumbnail, recycle, snapshot folders	francisrath	#3135 (francisrath)	3135	Y (User guide)
#3090 fix one book's series	francisrath	#2554 (magrhino)	2554	Y (API, Hardcover wiki); Metadata editing table row added
#3134 partly owned books in In Library	vavallee	#3132 (SturmB)	3132	Y (API); User guide meaning added
#3095 books in library per author	johnistheman	#3092 (johnistheman)	3092	GAP, fixed (User guide, API)
#3156 only a real umlaut flexes	vavallee	#3123 (vavallee)	3123	Y (search-design)
#3158 filing form in dedup key	vavallee	#3122 (vavallee)	3122	Y; DEPLOYMENT upgrade note added
#3160 rejected Hardcover token hold	vavallee	#3101 (vavallee)	3101	Y (API, DEPLOYMENT)
#3145 new author catalogue sync shown	francisrath	#3058 (francisrath)	3058	Y (API, User guide)
#3149 select arrow room on desktop	francisrath	#3148 (francisrath)	3148	N/A
#3147 proxy stored covers, No cover fallback	francisrath	#3146 (francisrath)	3146	N/A (same fields, now proxied)
#3125 book ratings in the UI	johnistheman	#3124 (johnistheman)	3124	GAP, fixed (User guide, API)
#3150 BnF provider	vavallee	#3144 (mnivoliez)	3144	Y (README, ARCHITECTURE, User guide, third-party-data); API value list added
#3173 genre weights by spread over books	francisrath	#3172 (francisrath)	3172	N/A
#3117, #3128, #3129, #3130 test hardening	francisrath	#1845, #1847, #1846, #1844 (vavallee)	none (test only)	N/A
#3171 set a book's cover from an uploaded image	francisrath	#3017 (francisrath)	3017	Y (API, User guide in the PR; status codes and ROADMAP added here)
#3174 error leaks	vavallee	none	api-error-leaks	Y (API)
#3176 one JSON error shape	vavallee	none	api-error-contract	Y (API Error format section)
#3175 security hardening	vavallee	#1640 (vavallee)	1640	Y (DEPLOYMENT, User guide, auth-oidc, troubleshooting-auth); linked folder note and ROADMAP added here
#3177 http static and downloads	vavallee	none	3177	Y (DEPLOYMENT)
#3185 db queries, migration 107, batched logs	vavallee	none	perf-db-queries	GAP, fixed (DEPLOYMENT Upgrading)
#3187 pollers, download retention, wanted envelope	vavallee	none	pollers-retention	Y (DEPLOYMENT, API, chart values); README env row and User guide added here
#3188 audit findings doc	vavallee	none	none	docs only, merged, no fragment needed
#3151 docs(claude) resource limits	vavallee	none	none	internal, not in the changelog

Credits and how each name was checked: the author or reporter fields from gh pr view and gh issue view of each row above. outside names: francisrath, johnistheman, magrhino, gchahcg, SturmB, mnivoliez. kragent66-glitch, foobarbigtime and the other v1.41.0 names have no merged PR or issue in this range, so they are not credited here.

Highest risk release note items (all in the CHANGELOG Upgrade notes): 413 instead of 400 for oversized bodies, JSON 404 and 405, Prowlarr test ok boolean, grab and retry 502 and no_download_client, download client test 502, delete containment (linked author folders need the target added as a root folder), OIDC providers list trimmed and redirect-base admin only, password change rate limit, BINDERY_DOWNLOAD_RETENTION_DAYS (first pass about 6 hours after startup, set 0 before the first start to keep rows), Queue hides imported rows after 7 days, wanted envelope only with limit, batched logs, migration 107.

Documentation changed (commit 1) and the PR each documents

File	Change	Documents
README.md	provider lists include Nasjonalbiblioteket and BnF as opt in primaries; series fix bullet; sort and counts bullet	#3150, #3090, #3125, #3095, #3088
docs/ROADMAP.md	Delivered: NB, BnF, own file covers, translation covers, series merge and per book fix, split editions (part of #2524, issue stays open), Norwegian and Swedish, ratings; Series discovery note	#3150, #3094, #3093, #3090, #2915, #2994, #3125
docs/User-Guide-Wiki.md	In Library meaning for partly owned books; ratings paragraph in what Bindery does not do; Authors list have / total, last name sort, author page sort and filters	#3134, #3125, #3095, #3116, #3088
docs/Metadata-Editing-Wiki.md	Series row in the edit table	#3090
docs/API.md	statistics.availableBookCount on the authors list; averageRating, ratingsCount, rating-asc / rating-desc; author search work counts; metadata.primary_provider values	#3095, #3125, #3127, #3150
docs/DEPLOYMENT.md	Upgrading: one time dedup key recompute; migration 107, retention first pass and batched logs; linked author folders under file deletes	#3158, #3185, #3187, #3175
README.md (env table)	BINDERY_DOWNLOAD_RETENTION_DAYS row	#3187
docs/User-Guide-Wiki.md (again)	Queue 7 day rule and retention; linked folder root note	#3187, #3175
docs/API.md (again)	cover upload status codes and response	#3171
docs/ROADMAP.md (again)	Delivered: cover upload, audit	#3171, #1640

Checked and left unchanged because already accurate on main: docs/third-party-data.md (BnF and NB sections exist, intro still says Google Books, Audnex and DNB are unreviewed, true), docs/ARCHITECTURE.md (provider and package list include BnF), docs/search-design.md (umlaut, NFD, filing form), docs/Storage-And-Hardlinks-Wiki.md (multi disc, .binderyignore), docs/DEPLOYMENT.md Hardcover quota and rejected token sections, docs/API.md mediaType + status=imported, hardcoverPausedUntil and hardcoverTokenRejected. One new variable, BINDERY_DOWNLOAD_RETENTION_DAYS (#3187), already in the DEPLOYMENT table and charts/bindery/values.yaml; I added the README row. Chart.yaml and image tag diffs are the deploy bot's. THIRD_PARTY_LICENSES.md unchanged: git diff v1.41.0..origin/main -- go.mod go.sum web/package.json web/package-lock.json is one line, toolchain go1.26.9 (the audit PRs may differ, recheck). docs/upgrade-v2.md does not exist (the file is docs/upgrade-v1.md) and nothing breaking shipped in the merged set, so no upgrade doc change.

Pre-tag checklist

• Every merged PR represented: inventory above; CHANGELOG commit greps clean for each PR number (docs(claude): local resource limits for parallel agent runs #3151 deliberately skipped, internal). Not final until the unmerged PRs land.
• Version matches SemVer: minor, reasoning above.
• docs/upgrade-v2.md extended if breaking: none of the merged PRs is breaking. The audit PRs change API statuses and file delete behaviour, covered by Upgrade notes in the changelog draft.
• CHANGELOG entry merged to main before tagging: not done, this PR is the vehicle.
• main green at the checked commit: ci.yml on ad01e3dc success; a run for 8129d39d (fix(recommender): weigh genres by their spread over books, not over genres (#3172) #3173) was in progress when checked. Built the merged tree myself: go build ./... and go vet ./... clean, tsc -b --noEmit clean (run under flock, GOMEMLIMIT=3GiB).
• Reporters and contributors credited by name (list above), verified from PR and issue author fields.
• Cut items vs shipping (nothing cut now; the audit set is in the release): the cut set became the audit drafts and they are now IN the release, so the question flips. Nothing merged can depend on them: main builds and vets clean without them. To confirm at the end: the stacked PRs (fix(api): one JSON error shape everywhere (stacked on #3174) #3176 on fix/api-error-leaks, perf(http): asset caching, uncapped file downloads, stored zips (audit PR 5) #3177 on fix/security-hardening) retarget to main cleanly once their bases merge; deleting a base branch on merge closes a stacked PR and GitHub will not reopen it, so merge the stack before deleting branches.
• Sibling consumers grepped, not re-audited:
  • InLibraryPredicate (fix(api): list partially owned books under In Library (#3132) #3134): used by the Books list filter and the authors list count. Suspicious, not changed: internal/db/requests.go:238 counts status = 'imported' per author for requests, OPDS (opds/builder.go, opds/helpers.go) and the Calibre and Grimmory syncers (ListByStatus(imported)) still key on status, so a partly owned dual format book is not offered over OPDS or synced to Calibre until its other format lands. Probably deliberate for OPDS (file based), worth a decision.
  • Proxied covers (fix(web): proxy stored covers on Wanted and Series, and show No cover when an image fails (#3146) #3147): proxyBookImages and proxySeriesImages now cover wanted and series; recommendations.go returns ImageURL with no proxy call, which is fine only while Discover carries provider URLs and never bindery-cover: references. Not verified, the web fallback covers the failure.
  • Hardcover hold consumers (fix(hardcover): stop asking with a rejected API token (#3101) #3160): IsProviderHold and CheckQuota callers are cmd/bindery/discovery_wiring.go, internal/metadata/aggregator.go, internal/migrate/outage.go, internal/abs/importer.go, internal/migrate/readarr.go, internal/migrate/csv.go, internal/scheduler/scheduler.go, internal/api/authors.go, cmd/bindery/main.go; nothing odd seen.
  • Umlaut keywords (fix(indexer): only a real umlaut may match a compact spelling (#3123) #3156): SigWords and authorTokens are consumed by indexer/release.go, indexer/searcher.go, indexer/newznab/*, importer/scanner.go, indexer/title_identity.go, metadata/aggregator.go, textutil/fold.go.
  • Dedup key (fix(indexer): fold the filing form into the dedup key (#3122) #3158): CanonicalDedupKey callers are in abs/import_utils.go, api/author_series_links.go, api/catalogue_reconciliation.go, db/books.go, db/db.go, metadata/aggregator_*, metadata/bnf and nb works, recommender/profile.go, seriesmatch/match.go.
• Re-landed reverts: none in git log v1.41.0..origin/main.
• Soak on dev: not satisfied, said bluntly. All of fix(api): stop raw database, filesystem and upstream text reaching clients #3174 to perf(api): trim finished downloads, page the wanted list, stop polling whole tables #3187 merged between about 01:00Z and 02:56Z on 2026-10-12. At my check (02:59Z) the last merge (perf(db): book lookups, history indexes, batched log writes, bounded cache eviction (audit PR 4) #3185) had been on main about three minutes, its dev deploy PR had not appeared yet and the main ci.yml run for it was still in progress. perf(api): trim finished downloads, page the wanted list, stop polling whole tables #3187 (retention, wanted envelope) reached dev at 02:56Z. A minor with an audit of nearly every API handler should sleep overnight on dev before the tag.
• Docs checks: make go-version-check passes; new prose grep clean for em dash, en dash and double hyphen (a few older em dashes remain on lines I appended to); make licenses-check not run (no dependency change in the merged set, CI runs it).

Known unverified items riding along

• BnF provider has never been run by a human in a real instance; about 22 live requests were made in development.
• fix(indexer): only a real umlaut may match a compact spelling (#3123) #3156: ASCII spelled German names no longer match releases that dropped the vowel (an accepted trade off, in the upgrade notes).
• Mobile CSS (fix(web): keep room for the select arrow on desktop too (#3148) #3149, fix(web): keep selects compact on touch screens (#3081) #3082) measured only in headless Chromium, not iOS Safari or Android Chrome.
• fix(web): proxy stored covers on Wanted and Series, and show No cover when an image fails (#3146) #3147 cover proxying across many endpoints and about 36 files, tested by unit tests only.
• fix(indexer): fold the filing form into the dedup key (#3122) #3158 backfill timing: 1.4 s for 100,000 books on the dev machine, not on a large real library.
• The audit changes the error text and status of nearly every API handler, tested by unit tests; no real client (web app, Readarr-style scripts, the Calibre bridge plugin) was driven against them by a human.
• Retention deletes data in the background (every finished download row past 90 days, in one pass about six hours after first start).
• The symlink fail closed change affects linked folder users: deletes leave files behind until the target is added as a root folder.
• Migration 107 timing (about half a second on 200,000 history rows) is the PR author's measurement.
• Not documented on purpose: nothing merged is undocumented as far as I found. docs/third-party-data.md still says Google Books, Audnex and DNB terms are unreviewed, which is accurate.

Test plan

• go build ./... and go vet ./...
• tsc -b --noEmit in web
• make go-version-check
• CI on this PR (docs are path ignored by some jobs; ABSTab.coverage is a known flake, Flaky test: ABSTab coverage test 'groups review items by run' fails intermittently in CI #3163)

🤖 Generated with Claude Code

https://claude.ai/code/session_016fJcCVbNnKsmj2MAAMwWj9

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!