From 376bdfbe93a091d1820ae1b33852af48d7ac6140 Mon Sep 17 00:00:00 2001
From: xzlknr <xzlknr@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:34:05 +0800
Subject: [PATCH] docs: add monorepo configuration guide

---
 README.md                      |   3 +
 ROADMAP.md                     |   2 +-
 docs/monorepo-configuration.md | 121 +++++++++++++++++++++++++++++++++
 3 files changed, 125 insertions(+), 1 deletion(-)
 create mode 100644 docs/monorepo-configuration.md

diff --git a/README.md b/README.md
index f0ff5db..c7a66f5 100644
--- a/README.md
+++ b/README.md
@@ -149,6 +149,9 @@ Run `pr-sheriff init` or add `.pr-sheriff.json` manually:
 Unknown configuration keys are rejected so typos cannot silently weaken a
 policy.
 
+For a small monorepo example with two packages, shared infrastructure, ignored
+docs, and sensitive paths, see the [monorepo configuration guide](docs/monorepo-configuration.md).
+
 ### Path-specific rules
 
 Different parts of a repository can have stricter review policies. Each matched
diff --git a/ROADMAP.md b/ROADMAP.md
index e8313e0..ffaed6c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -7,7 +7,7 @@ review. The roadmap is intentionally small and driven by maintainer feedback.
 
 - Add ready-to-copy policy presets for Python, JavaScript, and Rust projects.
 - Improve error messages and configuration validation.
-- Add documentation examples for common repository layouts.
+- Add documentation examples for common repository layouts, including the new [monorepo configuration guide](docs/monorepo-configuration.md).
 - Collect feedback from the first repositories using the Action.
 
 ## Next: better policy checks
diff --git a/docs/monorepo-configuration.md b/docs/monorepo-configuration.md
new file mode 100644
index 0000000..2b9cf64
--- /dev/null
+++ b/docs/monorepo-configuration.md
@@ -0,0 +1,121 @@
+# Monorepo configuration example
+
+PR Sheriff can help small monorepos keep pull requests reviewable, even before
+first-class package-level monorepo support is available. This guide shows a
+copyable starting point for a repository with two packages and shared
+infrastructure.
+
+## Example layout
+
+```text
+.
+├── packages/
+│   ├── api/
+│   │   ├── src/
+│   │   └── tests/
+│   └── web/
+│       ├── src/
+│       └── tests/
+├── infra/
+│   ├── terraform/
+│   └── migrations/
+├── docs/
+├── scripts/
+└── .github/workflows/
+```
+
+In this layout, `packages/api` and `packages/web` are separate application
+areas, while `infra`, `scripts`, and GitHub workflows are shared infrastructure
+that usually deserve closer review.
+
+## Copyable `.pr-sheriff.json`
+
+```json
+{
+  "max_changed_lines": 900,
+  "max_changed_files": 35,
+  "require_tests_after_lines": 120,
+  "test_patterns": [
+    "packages/*/tests/**",
+    "packages/**/*_test.*",
+    "packages/**/*.test.*",
+    "packages/**/*.spec.*",
+    "tests/**"
+  ],
+  "sensitive_patterns": [
+    ".github/workflows/**",
+    "infra/**",
+    "scripts/deploy/**",
+    "**/auth/**",
+    "**/migrations/**",
+    "**/Dockerfile",
+    "package-lock.json",
+    "poetry.lock"
+  ],
+  "ignore_patterns": [
+    "**/*.md",
+    "docs/**",
+    "packages/*/README.md"
+  ],
+  "path_rules": [
+    {
+      "name": "api package",
+      "patterns": ["packages/api/**"],
+      "max_changed_lines": 350,
+      "max_changed_files": 18,
+      "require_tests_after_lines": 60
+    },
+    {
+      "name": "web package",
+      "patterns": ["packages/web/**"],
+      "max_changed_lines": 450,
+      "max_changed_files": 22,
+      "require_tests_after_lines": 80
+    },
+    {
+      "name": "shared infrastructure",
+      "patterns": ["infra/**", ".github/workflows/**", "scripts/deploy/**"],
+      "max_changed_lines": 150,
+      "max_changed_files": 8,
+      "require_tests_after_lines": 1
+    }
+  ]
+}
+```
+
+## How to read this policy
+
+- The global limits keep very large cross-repository pull requests visible.
+- `test_patterns` count tests from both package-local test folders and a shared
+  top-level `tests/` folder.
+- `ignore_patterns` lets documentation-only changes avoid consuming the review
+  budget.
+- `sensitive_patterns` highlights shared infrastructure, deployment scripts,
+  authentication code, migrations, Dockerfiles, workflows, and lockfiles.
+- `path_rules` applies stricter thresholds to each package and to shared
+  infrastructure.
+
+## Current limitations
+
+PR Sheriff does not yet calculate separate risk scores per package. If a pull
+request touches both `packages/api` and `packages/web`, the global policy still
+sees one pull request, and each matching path rule reports its own violations.
+Use the path rule names to make review comments clearer, but do not treat them
+as independent package-level risk reports.
+
+PR Sheriff also does not understand package dependency graphs. For example, a
+change under `packages/api` that affects `packages/web` through generated types
+or shared contracts will not be inferred automatically. Keep shared contracts in
+sensitive paths or add a dedicated path rule for them.
+
+## Rollout pattern
+
+Start in advisory mode while contributors learn the policy:
+
+```bash
+pr-sheriff check --base origin/main --advisory
+```
+
+After the team agrees that the limits are useful, remove advisory mode in CI so
+policy violations fail the check. Keep the first thresholds generous, then lower
+them as the repository establishes normal pull request sizes.