diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 71d2fa59aa..995996b7d5 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 de69b15999..66237edf82 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 b274ae5775..b0402b9f21 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.