Say what the build is, not what happened to it - #172
Merged
Conversation
The README's connector line narrated a decision: five vendors "were reviewed and taken back out", and re-adding one "is a review of that vendor rather than a revert". Somebody reading a build doc to find out what this deployment can reach does not need the history of what it used to offer, and a sentence that only makes sense if you were there is worse than no sentence. It now says what the catalogue is and what a Bot is told about it. Two in the docs, the same fault: The identity-provider note explained the upstream plugin's scoping in the past tense, as though it had been fixed. It has not; that is what the plugin still does, which is the reason the routes exist. Present tense is both plainer and more accurate. The sign-in audit note described a world before those rows existed. Rewritten as what the rows are for. `docs/development.md` keeps its "no longer matches", which is the consequence of hand-editing a migration rather than a note about the past.
davidmckayv
requested review from
MikeRyanDev,
guidovizoso and
tylerslaton
as code owners
August 22, 2026 16:35
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.
The README's connector line was a diary entry:
Somebody reading a build doc to find out what this deployment can reach does not need the history of what it used to offer. "Rather than a revert" only parses if you were there for the removal. It now says what the catalogue is, and what a Bot is told about it:
Two more in the docs
architecture.mddescribed the upstream Better Auth scoping in the past tense — "two administrators saw two different deployments… would have deleted the company's sign-in" — as though it had been fixed upstream. It has not. That is what the plugin still does, and it is the reason OpenBot's own routes exist. Present tense is plainer and more accurate.architecture.mdalso described the world before sign-in audit rows existed. Rewritten as what the rows are for.deployment.mdsaid the app "no longer depends" on secure-context APIs. It does not depend on them; when it stopped is nobody's business.Left alone
docs/development.mdkeeps "a file that no longer matches what the generator produced" — that is the consequence of hand-editing a migration, not a note about the past.Swept the rest of the README and docs for the same pattern; the remaining past tense is all describing audit trail contents ("what was permitted, what was refused"), which is correct.