docs: require user-visible changes to ship with their docs, and credit AI tooling - #84
Merged
Merged
Conversation
Adds a "Documentation Is Part of the Change" section to AGENTS.md stating that any change a user can observe must land in the same PR as its docs update, with a routing table mapping change type to the file that owns it. Explicitly exempts refactors, internal helpers, test-only changes, and dependency bumps — if a user cannot tell the difference, neither can the docs. Also carries over two conventions the repo already learned the hard way: keep the README summary and the docs/ detail from duplicating each other (duplicated prose drifts exactly like the Biome pins did), and document the rationale behind non-obvious opt-in defaults.
A short footnote under Acknowledgements, above the license — stated plainly rather than as a headline, and paired with the fact that everything shipped was still reviewed, tested, and run in production.
This was referenced Sep 18, 2026
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
1 participant
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.
Two documentation changes.
AGENTS.md— Documentation Is Part of the ChangeA new section stating the rule directly: any change a user can observe must land in the same PR as its documentation update. It covers new features, settings, toggles, pages and job types; changed defaults and renamed settings; removals; and new or changed API endpoints and payloads.
It also says what doesn't need docs — refactors, internal helpers, test-only changes, dependency bumps. If a user cannot tell the difference, neither can the docs.
A routing table maps each kind of change to the file that owns it, so "where does this go?" isn't re-litigated per PR:
docs/settings.mddocs/<page>.mddocs/integrations.md## APIsection inREADME.mddocs/pageimages/Plus two conventions this repo already learned the expensive way:
docs/gets the detail. Repeating detail in both guarantees drift — the same failure mode as a version pinned in five places.general.fix_container_mismatchships off because enabling it makes an *arr recreate the file record and permanently losesceneName. A user reading only "corrects the file extension" would turn it on and be surprised.README.md— AcknowledgementsA short footnote above the license noting that AI coding tools were a substantial help in building this, alongside the fact that everything shipped was still reviewed, tested, and run in production. Deliberately a footnote, not a banner.
Verification
pre-commit run --all-filespasses clean (all 16 hooks). Docs-only change — no code paths touched, no rebuild required.