docs: 24 drift findings, every one verified against the code first - #595
Merged
Conversation
Closes #533 #534 #535 #536 #537 #538 #561 #562 #563 #564 #565 #566 #567 #568 #569 #570 #571 #572 #573 #589 #590 #591 #592 #593. A doc that describes behaviour the code no longer has is worse than no doc: it is a confident wrong answer, and for INSTALL and CONFIGURATION it is one an operator acts on while a broadcast is live. THE WORST ONE. CONFIGURATION.md told container operators to pass flags in `command:`. Docker's `command:` REPLACES the image's CMD -- which carries `-data /data` -- so DataDir fell back to `./data`, and with WORKDIR /data the server opened the empty /data/data and presented the FIRST-RUN PASSWORD SCREEN on a live install. The data is intact one directory up and nothing said so. Now a section that states the CMD, says `command:` replaces it, puts the config mount first, repeats `-data /data` in the flag form, and names the symptom alongside the reassurance. The compose file has no `command:` at all, so the old "shows both" was wrong twice. THE PORT. Three website snippets and QUICKSTART's `docker run` omitted `-p 1935:1935`, while the next step told the reader to pick RTMP -- a container with no RTMP ingest and nothing saying why. All are now byte-identical to README's, /udp note included, which is the classic silent-ingest failure. download.astro was NOT already fixed. It carried a caveat paragraph about the port while the copied string still lacked it, which is how it read as fixed to a reviewer and to me. Verified against the BUILT HTML rather than the source: ten snippets, all ten carry the trio. HOOKS.md said "No SSRF protection". There is: hooks.go refuses at save time, naming allowPrivateTarget -- a field documented nowhere in the repo. Now documented in HOOKS.md and API.md, with the refused ranges including Tailscale's CGNAT block, and the limitation corrected to what is actually true: hooks are defended, alert-rule webhooks are not. The Go floor was documented as 1.26.5 in SEVEN places against go.mod's 1.27.0 -- one more than the review found. Sweeping for other sites of each fact is what turned up the seventh Go-version site, the third bad snippet, and four further contradictions on the testing page whose counts had gone stale. That is RULE 5 of the fix brief and it earned its place every time it was applied. Claude-Session: https://claude.ai/code/session_01A8N3W5ct9SZtHK9sCDD9cL
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #533 #534 #535 #536 #537 #538 #561 #562 #563 #564 #565 #566 #567 #568 #569 #570 #571 #572 #573 #589 #590 #591 #592 #593.
All 24 confirmed real against the code — none stale, none already fixed.
The worst one — #533
CONFIGURATION.mdtold container operators to pass flags incommand:. Docker'scommand:replaces the image'sCMD, which carries-data /data— soDataDirfell back to./data, and withWORKDIR /datathe server opened the empty/data/dataand presented the first-run password screen on a live install. The data is intact one directory up and nothing said so.Now a section that states the CMD, says
command:replaces it, puts the config-file mount first, repeats-data /datain the flag form, and names the symptom alongside the reassurance. The compose file has nocommand:at all, so the old "shows both" was wrong twice over.The port — #534/#535
Three website snippets and
QUICKSTART.mdomitted-p 1935:1935while the next step told the reader to pick RTMP: a container with no RTMP ingest and nothing saying why. All now byte-identical to README's,/udpnote included.download.astrowas not already fixed. It carried a caveat paragraph about the port while the copied string still lacked it — which is how it read as fixed to the reviewer and to me. Verified against the built HTML, not the source: ten snippets, all ten carry the trio.#536
HOOKS.mdsaid "No SSRF protection". There is —hooks.gorefuses at save time, namingallowPrivateTarget, a field documented nowhere. Now inHOOKS.mdandAPI.mdwith the refused ranges (including Tailscale's CGNAT block), and the limitation corrected to what's true: hooks are defended, alert-rule webhooks are not.What sweeping found
RULE 5 — grep for every other site of a fact before calling it fixed — turned up a seventh Go-version site the review missed, the third bad snippet, and four stale counts on the testing page.
Not fixed — outside this assignment
CONTRIBUTING.md(Go 1.26.5+),config.example.yaml(missingtranscription:),CHANGELOG.md(no:443warning), and aRenditionsPage.tsxcomment. Listed in the report.One Warning where Control was possible (#533): Control is a startup check warning when
dataDiris empty and apolyemesis.dbsits beside it. That's a code change, recommended not made.npm run buildpasses — 38 pages, 0 errors. Go doc-drift tests green.https://claude.ai/code/session_01A8N3W5ct9SZtHK9sCDD9cL