docs: adoption fixes — recipes page, honest Windows status, 90s quickstart#77
Merged
Conversation
…start - New documentation/recipes.md (+es): copy-paste rules for the common jobs — gitleaks/ruff/semgrep as the check (with the staged-snapshot caveat), frozen paths via filename --forbid, architecture boundaries, conventional commits, CI/pre-commit/Husky/package.json/MCP configs. - README (+es): tool-as-check example inline (the 'point it at a tool you trust' claim is now demonstrated, not just stated), a 90-second violate->block->fix quickstart, uvx alongside npx/pipx, and a note on which install to pick (-g to try, --save-dev for teams). - Windows status made honest everywhere: beta, tracked in #31, first-class in v1.3 (README FAQ + stability.md get a Platform support section). - usage.md (+es): new 'Performance and limits' section — one process per rule, BECWRIGHT_CHECK_TIMEOUT, single rules.yaml per repo (monorepo scoping via globs), checks judge the staged snapshot. - CONTRIBUTING: map of the code + how to watch becwright police itself.
📝 WalkthroughWalkthroughThis PR updates documentation across the repository: CONTRIBUTING.md gains a code map, README.md/README.es.md expand install/demo guidance and add a blocking-rule walkthrough, new recipes.md/recipes.es.md pages document reusable rule examples and integrations, and stability/usage docs add platform support and performance notes. ChangesDocumentation updates
Estimated code review effort: 2 (Simple) | ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This was referenced Jul 3, 2026
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
README.es.md (1)
90-98: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueUntranslated CLI-output lines inside otherwise Spanish walkthrough.
Lines "Why it matters: un secreto..." mixes Spanish narration with
# >>> Commit BLOCKED: a blocking rule was broken.left in English, whereas the English README uses the same string as literal tool output. If this is meant to represent actual CLI output (not localized), it's fine and consistent with source; otherwise the Spanish variant should localize this line to stay true to the guideline that README.es.md is the Spanish counterpart of README.md.As per coding guidelines, "Maintain the Spanish README variant as the Spanish counterpart to the main README."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.es.md` around lines 90 - 98, The Spanish walkthrough in README.es.md still contains an English CLI-output line, so update the example around the blocking-rule output to keep the entire narrative localized and consistent with README.md’s Spanish counterpart. Specifically, adjust the quoted tool-output text in the demo section so the BLOCK / Commit BLOCKED message is presented in Spanish while preserving the same meaning and formatting style used by the rest of the walkthrough.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@documentation/usage.es.md`:
- Around line 240-242: Update the timeout documentation in
documentation/usage.es.md so it matches the behavior in src/becwright/engine.py:
the BECWRIGHT_CHECK_TIMEOUT setting disables the limit for any non-positive
value, not only 0. Adjust the wording around the check timeout description to
say that values <= 0 disable the cap, keeping the rest of the guidance about
seconds and slow full-repo runs unchanged.
In `@documentation/usage.md`:
- Around line 237-239: Clarify the timeout documentation to match runtime
behavior in src/becwright/engine.py: the check timeout cap is disabled for any
non-positive BECWRIGHT_CHECK_TIMEOUT value, not only 0. Update the usage text
near the hung check timeout note so it states “<= 0 disables the cap” (or
equivalent), keeping the wording aligned with the behavior implemented in the
timeout handling logic.
---
Nitpick comments:
In `@README.es.md`:
- Around line 90-98: The Spanish walkthrough in README.es.md still contains an
English CLI-output line, so update the example around the blocking-rule output
to keep the entire narrative localized and consistent with README.md’s Spanish
counterpart. Specifically, adjust the quoted tool-output text in the demo
section so the BLOCK / Commit BLOCKED message is presented in Spanish while
preserving the same meaning and formatting style used by the rest of the
walkthrough.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 402904c1-b63c-4dd4-844f-422bd334c4f3
📒 Files selected for processing (11)
CONTRIBUTING.mdREADME.es.mdREADME.mddocumentation/README.es.mddocumentation/README.mddocumentation/recipes.es.mddocumentation/recipes.mddocumentation/stability.es.mddocumentation/stability.mddocumentation/usage.es.mddocumentation/usage.md
Comment on lines
+240
to
+242
| - **Un check colgado no puede congelar tu commit.** Cada check tiene un tope de | ||
| 30 segundos; se ajusta con la variable de entorno `BECWRIGHT_CHECK_TIMEOUT` | ||
| (segundos; `0` desactiva el tope) para corridas lentas sobre todo el repo. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Aclarar el umbral que desactiva el timeout.
src/becwright/engine.py trata cualquier valor no positivo de BECWRIGHT_CHECK_TIMEOUT como desactivación del tope, no solo 0, así que conviene decir <= 0 para que la doc coincida con el comportamiento real.
♻️ Propuesta de fix
- segundos; se ajusta con la variable de entorno `BECWRIGHT_CHECK_TIMEOUT`
- (segundos; `0` desactiva el tope) para corridas lentas sobre todo el repo.
+ segundos; se ajusta con la variable de entorno `BECWRIGHT_CHECK_TIMEOUT`
+ (segundos; `<= 0` desactiva el tope) para corridas lentas sobre todo el repo.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Un check colgado no puede congelar tu commit.** Cada check tiene un tope de | |
| 30 segundos; se ajusta con la variable de entorno `BECWRIGHT_CHECK_TIMEOUT` | |
| (segundos; `0` desactiva el tope) para corridas lentas sobre todo el repo. | |
| - **Un check colgado no puede congelar tu commit.** Cada check tiene un tope de | |
| 30 segundos; se ajusta con la variable de entorno `BECWRIGHT_CHECK_TIMEOUT` | |
| (segundos; `<= 0` desactiva el tope) para corridas lentas sobre todo el repo. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@documentation/usage.es.md` around lines 240 - 242, Update the timeout
documentation in documentation/usage.es.md so it matches the behavior in
src/becwright/engine.py: the BECWRIGHT_CHECK_TIMEOUT setting disables the limit
for any non-positive value, not only 0. Adjust the wording around the check
timeout description to say that values <= 0 disable the cap, keeping the rest of
the guidance about seconds and slow full-repo runs unchanged.
Comment on lines
+237
to
+239
| - **A hung check cannot freeze your commit.** Every check is capped at 30 | ||
| seconds; override with the `BECWRIGHT_CHECK_TIMEOUT` environment variable | ||
| (seconds; `0` disables the cap) for slow whole-repo runs. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Clarify the timeout disable threshold.
src/becwright/engine.py treats any non-positive BECWRIGHT_CHECK_TIMEOUT value as disabling the cap, not just 0, so this should say <= 0 to match runtime behavior.
♻️ Proposed fix
- seconds; override with the `BECWRIGHT_CHECK_TIMEOUT` environment variable
- (seconds; `0` disables the cap) for slow whole-repo runs.
+ seconds; override with the `BECWRIGHT_CHECK_TIMEOUT` environment variable
+ (seconds; `<= 0` disables the cap) for slow whole-repo runs.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **A hung check cannot freeze your commit.** Every check is capped at 30 | |
| seconds; override with the `BECWRIGHT_CHECK_TIMEOUT` environment variable | |
| (seconds; `0` disables the cap) for slow whole-repo runs. | |
| - **A hung check cannot freeze your commit.** Every check is capped at 30 | |
| seconds; override with the `BECWRIGHT_CHECK_TIMEOUT` environment variable | |
| (seconds; `<= 0` disables the cap) for slow whole-repo runs. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@documentation/usage.md` around lines 237 - 239, Clarify the timeout
documentation to match runtime behavior in src/becwright/engine.py: the check
timeout cap is disabled for any non-positive BECWRIGHT_CHECK_TIMEOUT value, not
only 0. Update the usage text near the hung check timeout note so it states “<=
0 disables the cap” (or equivalent), keeping the wording aligned with the
behavior implemented in the timeout handling logic.
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.
What
External-adoption audit follow-ups (docs only), the P0 tier of the audit:
documentation/recipes.md(+.es) — copy-paste rules for the jobs people actually search for: gitleaks / ruff / semgrep as the check (with the staged-snapshot caveat: usegitleaks detect --no-git, notprotect), frozen critical paths viafilename --forbid '.*', architecture boundaries, conventional commits, plus complete CI / pre-commit / Husky / package.json / MCP configs. Closes the doc half of Provide a CI integration recipe (enforce BECs beyond the local hook) #28.uvxalongsidenpx/pipx run; an explicit note on which install to pick (-gto try,--save-devfor teams).stability.md). The old copy sounded more confident than the CI evidence supports.usage.md(+es): new Performance and limits section — one subprocess per rule,BECWRIGHT_CHECK_TIMEOUT, onerules.yamlper repo (monorepo scoping via globs), checks judge the staged snapshot.Test plan
pytestgreen locally (253 passed)Summary by CodeRabbit