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

* docs: add guidance for creating smaller, self-contained PRs

Co-Authored-By: Volnei Munhoz <volnei.munhoz@gmail.com>

* fix: remove PR size check from cubic-devin-review.yml per review feedback

Co-Authored-By: Volnei Munhoz <volnei.munhoz@gmail.com>

* docs: clarify PR size limits apply to code files only

Co-Authored-By: Volnei Munhoz <volnei.munhoz@gmail.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: volnei

.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

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)

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.