PR Templates

Pull request templates help ensure all PRs include necessary information. They guide contributors and maintain consistency across your project.

Why Use PR Templates?

Benefit	Description
Consistency	Every PR has the same structure
Completeness	Don't forget important information
Efficiency	Less back-and-forth asking for details
Onboarding	New contributors know what's expected

Creating a PR Template

Single Template

Create a file at one of these locations:

.github/PULL_REQUEST_TEMPLATE.md
.github/pull_request_template.md
docs/pull_request_template.md
PULL_REQUEST_TEMPLATE.md

The .github/ location is most common.

Basic Template Example

## Summary
<!-- Brief description of your changes -->

## Changes Made
<!-- List the specific changes -->
-
-
-

## Type of Change
<!-- Check all that apply -->
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
<!-- How did you test these changes? -->
- [ ] Unit tests pass
- [ ] Manual testing performed

## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review
- [ ] I have added necessary documentation
- [ ] My changes don't introduce new warnings

## Related Issues
<!-- Link any related issues -->
Closes #

Multiple Templates

For projects with different types of PRs:

Directory Structure

.github/
└── PULL_REQUEST_TEMPLATE/
    ├── bug_fix.md
    ├── feature.md
    └── documentation.md

Using Template Links

When creating a PR, add a query parameter:

https://github.com/owner/repo/compare/main...feature?template=feature.md

Or use the template dropdown in the GitHub UI.

Template Examples by Type

Feature Template

## Feature Description
<!-- What does this feature do? -->

## Motivation
<!-- Why is this feature needed? -->

## Implementation Details
<!-- Key technical decisions -->

## Screenshots
<!-- If applicable, add screenshots -->

## Breaking Changes
<!-- List any breaking changes -->
- None

## Migration Guide
<!-- If there are breaking changes, how to migrate -->

## Checklist
- [ ] Feature is complete
- [ ] Tests added
- [ ] Documentation updated
- [ ] No console.log statements
- [ ] Ready for review

Bug Fix Template

## Bug Description
<!-- What was the bug? -->

## Root Cause
<!-- What caused it? -->

## Solution
<!-- How did you fix it? -->

## Steps to Reproduce
<!-- How to reproduce the bug -->
1.
2.
3.

## Before/After
<!-- If visual, show before and after -->

## Testing
- [ ] Added test to prevent regression
- [ ] Verified fix locally
- [ ] Tested edge cases

## Related Issues
Fixes #

Documentation Template

## Documentation Change
<!-- What documentation is being updated? -->

## Reason for Change
<!-- Why is this change needed? -->

## Affected Pages
<!-- List pages that are affected -->
-

## Preview Link
<!-- If applicable, link to preview -->

## Checklist
- [ ] Spelling and grammar checked
- [ ] Links verified
- [ ] Code examples tested
- [ ] Images have alt text

Template Best Practices

Keep It Concise

Don't overwhelm contributors:

❌ Too long:

## Summary
## Background
## Motivation
## Implementation Details
## Technical Decisions
## Alternatives Considered
## Screenshots
## Performance Impact
## Security Impact
## Breaking Changes
## Migration Guide
## Documentation
## Testing
## Deployment Notes
## Rollback Plan
## Checklist

✅ Essential items:

## Summary
## Changes
## Testing
## Checklist

Use Comments for Guidance

## Summary
<!-- 1-2 sentences describing what this PR does -->

## Testing
<!-- Describe how you tested. Include steps if complex -->

Make Checklists Actionable

## Checklist
- [ ] Code follows style guide
- [ ] Tests pass locally
- [ ] Documentation updated (if needed)
- [ ] No sensitive data exposed

Include Examples

## Commit Message Format
<!-- Use conventional commits: type(scope): description -->
<!-- Examples: feat(auth): add login, fix(api): handle null -->

Conditional Sections

Use HTML comments for optional sections:

## Screenshots
<!-- Delete this section if no UI changes -->

## Breaking Changes
<!-- Delete if no breaking changes, otherwise list them -->
None

Integrating with Issues

Link templates to issue templates:

## Related Issues
<!--
Link issues using keywords:
- Closes #123 (closes when merged)
- Fixes #456 (same as closes)
- Relates to #789 (just links)
-->

Template Configuration

Enforce Template Usage

In repository settings:

• Require PR description
• Use branch protection rules

Default Labels

You can suggest labels in templates:

<!-- Please add appropriate labels: bug, feature, docs -->

But automatic labeling requires GitHub Actions or bots.

Automation with Templates

GitHub Actions Integration

Templates can prompt for automation:

## Deployment
- [ ] Ready for staging deployment
- [ ] Needs production deployment

<!--
Check 'Ready for staging' to trigger automatic deployment.
A maintainer will handle production deployment.
-->

Bot Commands

Some projects use bot commands in templates:

## Bot Commands
<!-- Uncomment to use -->
<!-- /deploy staging -->
<!-- /run-benchmarks -->

Summary

• PR templates ensure consistent, complete PRs
• Place template in .github/PULL_REQUEST_TEMPLATE.md
• Use multiple templates for different PR types
• Keep templates concise but comprehensive
• Include checklists for common requirements
• Use comments to guide contributors
• Link templates to issues and automation

In the next lesson, we'll learn about draft pull requests.