PR Description Templates for Monorepos
Monorepos are a double-edged sword. On one hand, they offer simplified dependency management, atomic changes across services, and easier code sharing. On the other, they introduce complexity, especially when it comes to code reviews and understanding the scope of a Pull Request (PR). In a monorepo, a single PR can touch anything from a core utility library to a specific frontend component, a backend API, or even infrastructure code. This diverse nature makes clear, comprehensive PR descriptions not just helpful, but absolutely critical.
Why Monorepos Make PR Descriptions Harder (And More Important)
Imagine a monorepo housing dozens of services and applications. A developer opens a PR. What does it change? Is it a minor CSS tweak in the web/app directory, a critical security patch in services/auth, or an infrastructure update to infra/kubernetes? Without a clear description, reviewers waste precious time digging through the diff to understand context, potential impact, and testing requirements.
Generic PR templates, like a single .github/pull_request_template.md file, often fall short in this environment. They might ask for "Summary" and "Test Plan," but these sections need to be vastly different depending on the type of change. A frontend change needs screenshots and browser compatibility notes, while a backend change requires details on API endpoints, database migrations, and performance considerations. A generic template simply can't capture this nuance, leading to either:
- Vague, unhelpful descriptions: Developers fill in generic answers that don't provide real value.
- Overly complex, ignored templates: The template becomes so long trying to cover all cases that developers skip sections or find it overwhelming.
- Manual template modification: Developers constantly delete or add sections, negating the benefit of a template.
The core problem is that in a monorepo, "one size fits all" templates are rarely effective. You need context-aware descriptions that guide the author and inform the reviewer, without adding unnecessary overhead.
Strategies for Dynamic PR Templates in Monorepos
So, how do you provide the right guidance for PRs in a monorepo without overwhelming everyone? Here are a few strategies, ranging from built-in Git features to custom automation.
1. Directory-Based Templates with GitHub's Feature
GitHub (and similar platforms like GitLab and Bitbucket) offers a simple, built-in mechanism for multiple PR templates. You can define different templates based on the directory a PR is initiated from.
For example, in your .github/pull_request_template/ directory, you could have:
.github/pull_request_template/
├── frontend.md
├── backend.md
├── infra.md
└── bug_fix.md
When a developer creates a new PR, they can choose from these options. For instance, frontend.md might look something like this:
### Summary
<!-- Briefly describe the changes in this PR. -->
### Type of change
- [ ] Feature
- [ ] Bug fix
- [ ] Refactor
- [ ] UI/UX Improvement
### Affected services/packages
<!-- List the specific services or packages impacted, e.g., `web/admin-dashboard`, `shared/components`. -->
### Screenshots (if applicable)
<!-- Add screenshots or GIFs of UI changes. -->
### Browser compatibility
- [ ] Chrome
- [ ] Firefox
- [ ] Safari
- [ ] Edge
### How was it tested?
<!-- Describe the testing you performed. -->
- Manual testing steps:
1. Go to [URL]
2. Click [X]
3. Verify [Y]
- Unit tests: [ ] Yes [ ] No
- Integration tests: [ ] Yes [ ] No
### Reviewer guidance
<!-- Specific areas you'd like the reviewer to focus on. -->
### Potential risks/side effects
<!-- Any known risks or implications for other parts of the system. -->
And backend.md could focus on API changes, database migrations, and performance:
### Summary
<!-- Briefly describe the changes in this PR. -->
### Type of change
- [ ] Feature
- [ ] Bug fix
- [ ] Refactor
- [ ] Performance
### Affected services/packages
<!-- List the specific services or packages impacted, e.g., `services/user-auth`, `shared/utils`. -->
### API changes (if applicable)
- New endpoints:
- Modified endpoints:
- Deprecated endpoints:
### Database changes (if applicable)
- Migrations run: [ ] Yes [ ] No
- Schema changes:
- Table:
- Columns:
### How was it tested?
<!-- Describe the testing you performed. -->
- Unit tests: [ ] Yes [ ] No
- Integration tests: [ ] Yes [ ] No
- End-to-end tests: [ ] Yes [ ] No
- Load/stress tests: [ ] Yes [ ] No
### Performance implications
<!-- Any expected impact on service performance. -->
### Reviewer guidance
<!-- Specific areas you'd like the reviewer to focus on. -->
### Potential risks/side effects
<!-- Any known risks or implications for other parts of the system. -->
Pitfalls: This approach still relies on the developer manually selecting the correct template. If a PR spans multiple types (e.g., a backend API change with a corresponding frontend update), the developer has to choose the "most relevant" one or merge sections manually, which can be cumbersome. It also doesn't automatically detect the scope.
2. Git Hooks or CI/CD Automation
For more dynamic and automated template selection, you can leverage Git hooks or CI/CD pipelines. The idea is to programmatically inspect the changes in a PR and then inject relevant sections into the description or even select an entirely different template.
You could write a simple script that runs as a pre-commit hook (less common for PR descriptions, but possible) or, more practically, as part of your CI pipeline when a PR is opened.
Here's a conceptual example using a shell script within a CI job (e.g., a GitHub Action or a Jenkinsfile):
```bash
!/bin/bash
This script would run in your CI pipeline
It checks which directories have been modified in the current PR.
PR_DESCRIPTION="" HAS_FRONTEND_CHANGES=$(git diff --name-only HEAD~1 HEAD | grep -q "web/" && echo "true" || echo "false") HAS_BACKEND_CHANGES=$(git diff --name-only HEAD~1 HEAD | grep -q "services/" && echo "true" || echo "false") HAS_INFRA_CHANGES=$(git diff --name-only HEAD~1 HEAD | grep -q "infra/" && echo "true