gh-bradleyboehmke-brads-marketplace-git-workflow/skills/pr-quality-standards.md

title, description, tags

title	description	tags
Pull Request Quality Standards	PR sizing, scope, documentation, and review-readiness criteria	github pull-requests standards code-review collaboration

Pull Request Quality Standards

Metadata

Purpose: Define what makes a good PR at (size, focus, documentation) Applies to: All pull requests in projects Version: 1.0.0

---

Instructions

Single-Purpose Principle

Each PR should do ONE thing well

A PR should represent a single, cohesive change:

• One feature
• One bug fix
• One refactoring
• One set of related documentation updates

❌ Multi-purpose PRs (avoid these):

• Feature + unrelated bug fixes
• Refactoring + new functionality
• Multiple independent features
• Bug fixes + dependency updates + docs

Why it matters:

• Easier to review and understand
• Clearer rollback if issues arise
• Better Git history for debugging
• Faster review cycles

PR Size Guidelines

Target sizes (lines of code changed):

• Small: < 200 LOC ✅ (ideal, ~1-2 hours review time)
• Medium: 200-500 LOC ⚠️ (acceptable, ~2-4 hours review time)
• Large: 500-1000 LOC ⚠️ (needs justification, ~1 day review time)
• Too Large: > 1000 LOC ❌ (should be split)

File count: Aim for < 15 files changed

Exceptions (large PRs acceptable when):

• Generated code (migrations, API clients)
• Vendored dependencies
• Large data files or configuration
• Initial project setup
• Bulk renaming/reformatting (use separate PR)

When PR is too large, split by:

• Logical components (backend → frontend)
• Sequential steps (refactor → feature → tests)
• Module/service boundaries
• Infrastructure vs application changes

Title Format

Use clear, descriptive titles:

<type>: <clear description of change>

Examples:

• ✅ feat: add customer segmentation API endpoint
• ✅ fix: resolve race condition in order processing
• ✅ refactor: extract validation logic to shared utilities
• ❌ updates (too vague)
• ❌ fix bug (which bug?)
• ❌ Feature/123 (not descriptive)

Title should:

• Start with lowercase (after type)
• Use imperative mood
• Be specific about what changed
• Avoid ticket numbers only (include description)

Description Requirements

Minimum requirements for all PRs:

1. Purpose: Why is this change needed?
2. Changes: What was modified (high-level)?
3. Testing: How was this tested?
4. Impact: What's affected by this change?
5. Issue Reference: Link to related GitHub issue(s)

Issue Linking Policy for PRs

Issue references are REQUIRED for:

• Feature PRs (new functionality)
• Bug fix PRs (resolving issues)
• Breaking change PRs
• Large refactorings (> 200 LOC)

Issue references are RECOMMENDED for:

• Performance improvements
• Smaller refactorings
• Significant test additions

Issue references are OPTIONAL for:

• Documentation-only updates
• Dependency updates (chores)
• Minor formatting/style fixes

Format in PR description:

• Closes #123 - Closes an issue when PR merges
• Fixes #456 - Fixes a bug (auto-closes issue)
• Resolves #789 - Resolves an issue
• Relates to #101 - Related but doesn't auto-close
• Part of #102 - Part of larger epic/feature
• Multiple issues: Closes #123, #456

Placement: Include in Purpose section or at end of description

Examples:

## Purpose
Add email validation to prevent registration with invalid addresses.

Closes #234

## Purpose
Fix session timeout issue reported by multiple mobile users.

This addresses the root cause identified in investigation.

Fixes #456

Template:

## Purpose
Brief explanation of why this change is needed.

## Changes
- High-level summary of what was modified
- Key technical decisions
- Any breaking changes

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Tested on [environment/platform]

## Screenshots (if UI changes)
[Add screenshots or recordings]

## Impact
- Who/what is affected?
- Any performance implications?
- Dependencies or follow-up work?

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests added for new functionality
- [ ] Documentation updated
- [ ] No debugging code or console logs

Multi-Purpose PR Detection

Red flags indicating a multi-purpose PR:

🚩 Multiple unrelated file groups:

Changes:
- src/auth/*           (authentication changes)
- src/reports/*        (reporting feature)
- src/database/*       (schema updates)

→ Split into 3 PRs

🚩 Commit history with mixed types:

feat: add new dashboard
fix: resolve login issue
chore: update dependencies
docs: update README

→ Each should be separate PR

🚩 Description uses "and" repeatedly:

"This PR adds user authentication AND fixes the bug in reports
AND updates dependencies AND refactors the API"

→ Split into 4 PRs

🚩 Changes span multiple services/repos: → Consider separate PRs per service, or use stack of dependent PRs

Draft PRs

Use draft PRs for:

• Work in progress (WIP)
• Seeking early feedback
• Sharing approach before completion
• Long-running feature branches

Mark as draft when:

• Tests aren't passing
• Code isn't ready for review
• Exploring an approach

Convert to ready when:

• All tests pass
• Code is complete
• Ready for full review

---

Resources

Size Refactoring Strategies

Strategy 1: Layer-based splitting

PR 1: Database schema changes
PR 2: Backend API implementation
PR 3: Frontend integration
PR 4: Tests and documentation

Strategy 2: Feature-based splitting

PR 1: Core feature (minimal viable)
PR 2: Additional options/configuration
PR 3: UI polish and edge cases
PR 4: Performance optimizations

Strategy 3: Refactor-then-feature

PR 1: Refactor existing code (no behavior change)
PR 2: Add new feature using refactored structure

Strategy 4: Component isolation

PR 1: Shared utilities (used by feature)
PR 2: Service A changes
PR 3: Service B changes
PR 4: Integration and tests

Good PR Examples

Example 1: Small, focused feature

Title: feat: add email validation to user registration

Description:
## Purpose
Users were able to register with invalid email addresses, causing
delivery failures for password reset emails.

## Changes
- Added regex-based email validation in registration form
- Added backend validation in user creation endpoint
- Display user-friendly error for invalid emails

## Testing
- [x] Unit tests for validation logic
- [x] Integration tests for registration flow
- [x] Manual testing with various email formats

## Impact
- Affects new user registration only
- Existing users unaffected
- No database changes required

Files changed: 4 (+120, -15)

Example 2: Well-scoped refactor

Title: refactor: extract common validation logic to utilities

Description:
## Purpose
Validation logic was duplicated across 8 API endpoints, making
updates error-prone and inconsistent.

## Changes
- Created validation utilities module
- Extracted email, phone, date validation to shared functions
- Updated 8 endpoints to use shared validators
- No behavior changes (existing tests still pass)

## Testing
- [x] All existing unit tests pass unchanged
- [x] Added tests for new validation utilities
- [x] Manual regression testing on auth flows

## Impact
- All API endpoints using validation
- Easier to add new validation rules in future
- No user-facing changes

Files changed: 12 (+250, -180)

PR Review Checklist

For PR authors (self-review):

• Single, focused purpose
• Reasonable size (< 500 LOC if possible)
• Clear title and description
• All tests passing
• No commented-out code
• No console.log / debugging statements
• Documentation updated
• Breaking changes clearly marked
• Follow-up issues created for future work

For reviewers:

• Purpose is clear and justified
• Changes match description
• No scope creep or unrelated changes
• Code follows standards
• Tests are adequate
• No security issues
• Performance impact acceptable
• Documentation sufficient

Breaking Change Communication

If PR includes breaking changes:

1. Mark clearly in title:

   feat!: change authentication to OAuth2
   

2. Add BREAKING CHANGE section:

   ## BREAKING CHANGE
   
   The `/auth` endpoint now requires OAuth2 tokens instead of API keys.
   
   **Migration guide**:
   1. Register OAuth2 application
   2. Update client to obtain tokens
   3. Replace API key header with Bearer token
   
   **Timeline**: Old authentication deprecated 2024-06-01, removed 2024-09-01
   

3. Communicate to stakeholders:

   • Tag affected teams in PR
   • Post in relevant Slack channels
   • Update migration documentation

Personal Patterns

Research PRs: Include experiment context

## Research Context
- **Hypothesis**: XGBoost will improve prediction accuracy by 5%
- **Baseline**: Current model (Random Forest, 0.82 AUC)
- **Metrics**: AUC, precision, recall on validation set
- **Outcome**: Document results in PR comments

Data pipeline PRs: Include data impact

## Data Impact
- **Affected tables**: customer_data, transactions
- **Estimated runtime**: +15 minutes per run
- **Backfill needed**: Yes, for records since 2024-01-01
- **Validation queries**: [link to SQL validation]

Multi-repo PRs: Link related PRs

## Related PRs
- API service: #123
- Web app: #456
- Data pipeline: #789

**Merge order**: API → Pipeline → Web App

Handling Large PRs (When Unavoidable)

If you must create a large PR:

1. Provide detailed description with section breakdown
2. Add inline comments explaining complex sections
3. Create review guide:

   ## Review Guide
   
   Recommended review order:
   1. Start with `src/models/*.py` (core logic)
   2. Then `src/api/*.py` (API changes)
   3. Then `tests/*` (test coverage)
   4. Finally `docs/*` (documentation)
   
   Focus areas:
   - Data validation logic in `validators.py`
   - Performance of batch processing in `processor.py`
   

4. Break into logical commits that can be reviewed individually
5. Offer to pair review for complex sections