Skip to content

Scheduling infrastructure for absolutely everyone.

docs: add guidance for creating smaller, self-contained PRs (#27155)

Volnei Munhoz1c09413ef4ca
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 71d2fa59aae..995996b7d59 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -42,3 +42,4 @@ A visual demonstration is strongly recommended, for both the original and new ch
- My code doesn't follow the style guidelines of this project
- I haven't commented my code, particularly in hard-to-understand areas
- I haven't checked if my changes generate no new warnings
+- My PR is too large (>500 lines or >10 files) and should be split into smaller PRs
diff --git a/AGENTS.md b/AGENTS.md
index de69b15999b..66237edf824 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,49 @@ You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioriti
- Never skip running type checks before pushing
- Never create large PRs (>500 lines or >10 files) - split them instead
+## PR Size Guidelines
+
+Large PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.
+
+### Size Limits
+
+- **Lines changed**: Keep PRs under 500 lines of code (additions + deletions)
+- **Files changed**: Keep PRs under 10 code files
+- **Single responsibility**: Each PR should do one thing well
+
+**Note**: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.
+
+### How to Split Large Changes
+
+When a task requires extensive changes, break it into multiple PRs:
+
+1. **By layer**: Separate database/schema changes, backend logic, and frontend UI into different PRs
+2. **By feature component**: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)
+3. **By refactor vs feature**: Do preparatory refactoring in a separate PR before adding new functionality
+4. **By dependency order**: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)
+
+### Examples of Good PR Splits
+
+**Instead of one large "Add booking notifications" PR:**
+- PR 1: Add notification preferences schema and migration
+- PR 2: Add notification service and API endpoints
+- PR 3: Add notification UI components
+- PR 4: Integrate notifications into booking flow
+
+**Instead of one large "Refactor calendar sync" PR:**
+- PR 1: Extract calendar sync logic into dedicated service
+- PR 2: Add new calendar provider abstraction
+- PR 3: Migrate existing providers to new abstraction
+- PR 4: Add new calendar provider support
+
+### Benefits of Smaller PRs
+
+- Faster review cycles and quicker feedback
+- Easier to identify and fix issues
+- Lower risk of merge conflicts
+- Simpler to revert if problems arise
+- Better git history and easier debugging
+
## Commands
### File-scoped (preferred for speed)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b274ae5775a..b0402b9f215 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -190,6 +190,22 @@ If you get errors, be sure to fix them before committing.
## Making a Pull Request
+### Keep PRs Small and Focused
+
+Large PRs are difficult to review and more prone to errors. We strongly encourage smaller, self-contained PRs:
+
+- **Size limits**: Keep PRs under 500 lines of code changed and under 10 code files modified (excludes documentation, lock files, and auto-generated files)
+- **Single responsibility**: Each PR should address one concern (one feature, one bug fix, or one refactor)
+- **Split large changes**: If your task requires extensive changes, break it into multiple PRs that can be reviewed and merged independently
+
+**How to split large changes:**
+- Separate database/schema changes from application logic
+- Split frontend and backend changes when possible
+- Do preparatory refactoring in a separate PR before adding new features
+- Create PRs in dependency order (infrastructure first, then features)
+
+### PR Checklist
+
- Be sure to [check the "Allow edits from maintainers" option](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) when creating your PR. (This option isn't available if you're [contributing from a fork belonging to an organization](https://github.com/orgs/community/discussions/5634))
- If your PR refers to or fixes an issue, add `refs #XXX` or `fixes #XXX` to the PR description. Replace `XXX` with the respective issue number. See more about [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
- Fill out the PR template accordingly.