docs: server comments say what the code does, not how it came to be (#6277)

Comment blocks in cmd/minstrel and 30 smaller internal packages, rewritten
to rule 32's standard with each citation read in context: task, milestone
and rule ids go, and so do the stories they were attached to ("used to",
"Before #N", measurements from one install, quotes, pointers to Fabled
Librarian's records and to docs/superpowers files that are not in the
repo). Where a story wrapped a real constraint, the constraint stays as a
present-tense fact.

Comments that had gone stale are corrected:
- taste.Config: the tuned values are overlaid by internal/recsettings;
  it is no longer "a later follow-up".
- StorageConfig: the data dir holds art, caches and the stream secret,
  not only playlist covers.
- the Subsonic album list and getUser comments describe what they do
  today rather than a milestone that would change it.

Checked: the non-comment token stream of every changed file matches
HEAD, and gofmt -l is empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 12:15:05 -04:00
co-authored by Claude Opus 5.5
parent 9f9609591d
commit d191a28217
107 changed files with 485 additions and 597 deletions
+5 -7
View File
@@ -1,6 +1,4 @@
// Package lifecycle looks after a download from the grab to its removal
// (M502 #5523), ported from Fabled Librarian's internal/health and its seed
// release (System 104).
// Package lifecycle looks after a download from the grab to its removal.
//
// - A download the client has failed is given up at once.
// - One nobody has shared, or still fetching its file list, after the
@@ -75,7 +73,7 @@ const (
// goneAfter: a client restarting can answer without a download for a
// while; half an hour missing is gone.
goneAfter = 30 * time.Minute
// goneWindow: a release gone twice within it is held back (#6176).
// goneWindow: a release gone twice within it is held back.
goneWindow = 7 * 24 * time.Hour
)
@@ -335,7 +333,7 @@ func (s *Service) judge(ctx context.Context, q *dbq.Queries, d downloader.Driver
}
// The client's own verdict, given up on at once: it has already made
// the decision a retry would ask about (FL #4749).
// the decision a retry would ask about.
if t.Failed() {
why := t.FailReason
if why == "" {
@@ -445,8 +443,8 @@ func (s *Service) giveUp(ctx context.Context, q *dbq.Queries, d downloader.Drive
// endGone ends a grab whose download left the client, and searches again.
// The first time, the release is not held back: nothing was found wrong with
// it. A release that leaves its client again within goneWindow is held back for
// acquire.GoneBlock (#6176): whatever keeps the client from listing it, taking
// it again on every pass found 38 grabs of one release in a day.
// acquire.GoneBlock: whatever keeps the client from listing it would otherwise
// have it taken again on every pass.
func (s *Service) endGone(ctx context.Context, q *dbq.Queries, g dbq.ListLiveGrabsRow, rep *Report) {
detail := "The download client no longer lists it: removed outside Minstrel. The album is searched for again."
before, err := q.CountGoneGrabs(ctx, dbq.CountGoneGrabsParams{
+1 -1
View File
@@ -279,7 +279,7 @@ func TestLifecycle_ADownloadGoneFromTheClientEndsAfterHalfAnHour_Integration(t *
}
// A release that leaves its client a second time is held back, whatever the
// cause (#6176): one release was taken 40 times in a day, each ending gone.
// cause, so it is not taken again on every pass.
func TestLifecycle_AReleaseGoneTwiceIsHeldBack_Integration(t *testing.T) {
st := newStack(t, downloader.Torrent{Name: "Daft Punk - RAM [FLAC]", Progress: 0.3, State: "downloading", NumSeeds: 4})
ctx := context.Background()