Skip to content

docs: fix v0.2.0 release-audit documentation drift - #601

Merged
badbread merged 1 commit into
mainfrom
docs/release-audit-cleanup
Aug 9, 2026
Merged

docs: fix v0.2.0 release-audit documentation drift#601
badbread merged 1 commit into
mainfrom
docs/release-audit-cleanup

Conversation

@badbread

@badbread badbread commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Summary

Nine evidence-backed fixes from a v0.2.0 documentation/runbook audit. No code changes except forwarding SEGMENT_RECEIPT_TIMEOUT_SECS through compose (item 6) so an existing recorder log line's advice is actually true.

  1. Migration range 0072-0078 -> 0072-0080 (docs/COMPOSE.md, docs-site/docs/getting-started/upgrade-and-rollback.md). Also reworded COMPOSE.md's "GO2RTC_AUTH is the only new key" to mention MAIN_REPAIR_TRANSCODE_ENABLED too.
  2. Secrets docs overclaimed _FILE support for go2rtc credentials. GO2RTC_USER_FILE/GO2RTC_PASS_FILE don't work end to end (the embedded go2rtc reads the plain env vars directly, and compose :?-requires them). Scoped the _FILE-supported list to DATABASE_URL, JWT_SECRET, SEED_ADMIN_PASSWORD, HA_TOKEN in docs-site/docs/configuration/secrets.md and environment-reference.md.
  3. docs/OPS-DEPLOY.md documented a nonexistent scripts/setup-env.sh --print flag. The parser only accepts --force/--prompt/-h. Replaced with the actual way to see the passphrase again (it's in .env as SEED_ADMIN_PASSWORD).
  4. Stale DB_POOL_SIZE guidance. docs/OPS-DEPLOY.md said it needed hand-wiring into the environment blocks; the stock compose already forwards it and .env.example carries the commented key.
  5. Backup-runbook contradiction. docs/OPS-DEPLOY.md and docs/OPS-BACKUP-RECOVERY.md only taught the manual scripts/backup-db.sh + cron path and never mentioned the api's built-in nightly pg_dump (on by default). Added a note to both framing the manual script as supplemental/ad-hoc.
  6. Recorder log advised an env var compose never forwarded. services/recorder/src/recording.rs tells the operator to raise SEGMENT_RECEIPT_TIMEOUT_SECS, but it wasn't in the recorder's compose environment: block. Confirmed unset/unparseable safely falls back to the internal default (no panic, no zero-timeout) via clamp_segment_receipt_timeout_secs, so forwarding it is safe: added it to docker-compose.yml, .env.example, and the environment reference.
  7. docs/ROADMAP.md "where we are today" was badly stale. The notification system described as "a single hardcoded webhook watchdog" is actually a full rules/channels/history engine (Discord, Slack, Pushover, Telegram, ntfy, webhook dispatchers; quiet hours; snooze/presence) shipped well before 0.2.0 and redesigned in the console by feat(notifications): redesign the console Notifications pane (channels, alert-text editor, quiet hours) #583. The distribution initiative claimed "no registry wired" and "CI does not build the APK", both shipped (public GHCR, signed Android releases via android-release.yml, version.properties at 0.2.0/5). Rewrote the "where we are today" passages and checked off the phase-checklist items that are actually done.
  8. Plate naming was undocumented. Added a section to the LPR docs page covering naming a plate (distinct from watchlisting), that the name renders everywhere the plate appears, and copy-plate-number, shipped on all four clients (web, desktop, Android, iOS).
  9. mainv documentation drift. docs/COMPONENT-MAP.md still documented the pre-fix(android): try the repaired main (mainv) before the doomed raw main #594 fallback order (main -> mainv -> ...); the code is mainv-first after fix(android): try the repaired main (mainv) before the doomed raw main #594. Also corrected the stale sdp_video_lacks_fmtp-on-producer detection detail to the actual served-SDP check (stream_served_video_lacks_fmtp, post-fix(api): flag the _mainv repair from the SERVED SDP, not the producer #592). Added a correction addendum to the relevant docs/DECISIONS.md entry (matching its existing addendum style) rather than editing the original decision text.

Test plan

  • docker compose -f docker-compose.yml config -q validated clean on dev2 (real Docker, not a YAML parser) with the new SEGMENT_RECEIPT_TIMEOUT_SECS key rendering correctly
  • No em-dashes/en-dashes introduced (checked the diff)
  • Every fix cross-checked against the actual code/config it describes (see commit body for specifics)

Nine evidence-backed fixes from a v0.2.0 documentation/runbook audit:

1. Migration range 0072-0078 corrected to 0072-0080 (COMPOSE.md,
   upgrade-and-rollback.md), and the "GO2RTC_AUTH is the only new key"
   claim reworded to also mention MAIN_REPAIR_TRANSCODE_ENABLED.
2. Secrets docs no longer claim GO2RTC_USER_FILE/GO2RTC_PASS_FILE work,
   those two don't support the _FILE convention end to end (embedded
   go2rtc reads process env directly, compose requires the plain vars).
3. Removed the nonexistent scripts/setup-env.sh --print flag from
   OPS-DEPLOY.md; pointed at the passphrase already sitting in .env
   instead.
4. Corrected the stale DB_POOL_SIZE guidance in OPS-DEPLOY.md, it is
   already forwarded by the stock docker-compose.yml.
5. Added a note to OPS-DEPLOY.md and OPS-BACKUP-RECOVERY.md that
   automated nightly backups are on by default (docs/BACKUP.md);
   scripts/backup-db.sh is framed as the supplemental/ad-hoc path.
6. Forwarded SEGMENT_RECEIPT_TIMEOUT_SECS in docker-compose.yml's
   recorder environment block so the recorder's log advice to raise it
   is actually true (unset/unparseable safely falls back to the
   internal default, confirmed in recording.rs); documented it in
   .env.example and the environment reference.
7. Rewrote ROADMAP.md's stale "where we are today" for the notification
   system (a full rules/channels/history engine already shipped) and
   prebuilt distribution (GHCR + signed Android releases are live),
   checking off the phase-checklist items that are actually done.
8. Documented plate naming and copy-plate-number on the LPR docs page,
   shipped on all four clients.
9. Corrected the Android mainv-first stream-fallback order and the
   served-vs-producer SDP detection detail in COMPONENT-MAP.md, and
   added a correction addendum to the DECISIONS.md entry.

Signed-off-by: badbread <badbread@users.noreply.github.com>
@badbread
badbread merged commit bac1d3a into main Aug 9, 2026
8 checks passed
@badbread
badbread deleted the docs/release-audit-cleanup branch August 9, 2026 03:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant