yolo/arr
3
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

Amend DESIGN.md for TV tracking decisions #117

New Issue
Closed
opened 2026-08-23 15:55:55 +01:00 by naps62-yolo · 0 comments
naps62-yolo commented 2026-08-23 15:55:55 +01:00
Owner
Copy Link
Copy Source

Three TV tracking decisions extend or contradict the current text. The document
is the contract, so it changes before the code that assumes it. Every other
issue in this batch depends on this one.

§4.1 — Season.tracked is a rule, not decoration. The section describes
Series.auto_track and leaves Season.tracked unexplained, and nothing in the
codebase reads it. Give it a meaning: a tracked season marks newly revealed
episodes wanted, and turning it on marks every already-revealed episode in that
season wanted. Turning it off withdraws nothing — leaf intent is never removed
implicitly. auto_track keeps its own meaning one level up: when metadata
reveals a new season, that season becomes tracked.

§4.1 and §4.2 — season 0 is excluded. Specials are dozens of undated shorts
and recaps that indexers do not carry. auto_track must never mark season 0
tracked, and derived status must ignore season 0 episodes entirely, so a
manually wanted special cannot pin a series at incomplete or hold back
ended. The accepted consequence: specials are visible and grabbable in the
series detail view, and invisible to status.

§6.2 and §14 — RSS skips packs for a started season. §6.2 says every wanted
item is matched against every RSS result forever, which taken literally lets a
season pack satisfy one missing episode of a season already half on disk. §14
already refuses to re-grab a pack over episodes on disk; state that the RSS lane
obeys the same guard, so both lanes agree and a season does not behave
differently depending on which lane sees a release first. A pack for a season
with nothing on disk stays eligible. The manual escape hatch when a single
episode cannot be found is the season release deck, not a lane exception.

Documentation only. No code changes.

Three TV tracking decisions extend or contradict the current text. The document is the contract, so it changes before the code that assumes it. Every other issue in this batch depends on this one. **§4.1 — `Season.tracked` is a rule, not decoration.** The section describes `Series.auto_track` and leaves `Season.tracked` unexplained, and nothing in the codebase reads it. Give it a meaning: a tracked season marks newly revealed episodes wanted, and turning it on marks every already-revealed episode in that season wanted. Turning it off withdraws nothing — leaf intent is never removed implicitly. `auto_track` keeps its own meaning one level up: when metadata reveals a new season, that season becomes tracked. **§4.1 and §4.2 — season 0 is excluded.** Specials are dozens of undated shorts and recaps that indexers do not carry. `auto_track` must never mark season 0 tracked, and derived status must ignore season 0 episodes entirely, so a manually wanted special cannot pin a series at `incomplete` or hold back `ended`. The accepted consequence: specials are visible and grabbable in the series detail view, and invisible to status. **§6.2 and §14 — RSS skips packs for a started season.** §6.2 says every wanted item is matched against every RSS result forever, which taken literally lets a season pack satisfy one missing episode of a season already half on disk. §14 already refuses to re-grab a pack over episodes on disk; state that the RSS lane obeys the same guard, so both lanes agree and a season does not behave differently depending on which lane sees a release first. A pack for a season with nothing on disk stays eligible. The manual escape hatch when a single episode cannot be found is the season release deck, not a lane exception. Documentation only. No code changes.
naps62-yolo added the area/infraphase/6-tvdifficulty/easytype/chore labels 2026-08-23 15:55:55 +01:00
naps62-yolo added this to the TV tracking milestone 2026-08-23 15:58:35 +01:00
naps62-yolo added a new dependency 2026-08-23 16:36:55 +01:00
#119 Make seasons.tracked govern episode intent
naps62-yolo added a new dependency 2026-08-23 16:36:55 +01:00
#118 Exclude season 0 from auto_track and derived status
naps62-yolo added a new dependency 2026-08-23 16:36:55 +01:00
#121 Daily series metadata refresh
naps62-yolo added a new dependency 2026-08-23 16:36:55 +01:00
#123 Episode and season-pack matching in arr-core
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/api
arr-api
 area/ci
CI and test harness
 area/compat
arr-compat
 area/core
arr-core
 area/daemon
arr-daemon
 area/db
arr-db
 area/dl
arr-dl
 area/indexer
arr-indexer
 area/infra
workspace and tooling
 area/meta
arr-meta
 area/parse
arr-parse
 area/probe
arr-probe
 area/subs
arr-subs crate: providers, extraction, translation, sync
 area/web
web/
 difficulty/easy
bounded, obvious approach, few files
 difficulty/hard
subtle correctness or cross-cutting
 difficulty/moderate
multiple files, judgement, an interface to design
 difficulty/trivial
one file, mechanical, no design decisions
 phase/1-skeleton
workspace, CI, config, database, empty API and SPA
 phase/2-logic
parsing and policy engine, pure, no network
 phase/3-sourcing
TMDB and Prowlarr, read-only
 phase/4-movies
movies end to end
 phase/5-ui
search, buckets, library views, queues
 phase/6-tv
seasons, episodes, tracking, derived status
 phase/7-people
owner tags and notifications
 phase/8-compat
Jellyseerr shim
 phase/9-subtitles
build order: subtitles, DESIGN.md §15
 type/bug
type/chore
type/feature
type/test
No labels area/infra difficulty/easy phase/6-tv type/chore
Milestone
No items
No Milestone TV tracking
Projects
Clear projects
No projects
Assignees
Clear assignees
hermes (Hermes (agent)) naps62 (Miguel Palhas) naps62-yolo (naps62-yolo (agent))
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#119 Make seasons.tracked govern episode intent
yolo/arr
#118 Exclude season 0 from auto_track and derived status
yolo/arr
#121 Daily series metadata refresh
yolo/arr
#123 Episode and season-pack matching in arr-core
yolo/arr
Reference: yolo/arr#117