pr-guidelines

从Graphite和GitHub指南中提炼的pull request最佳实践。当创建pull requests并与graphite-workflow技能一起使用以确保它们遵循大小指南、包含适当的上下文并促进高效的审查时使用。涵盖PR堆叠、描述模板、审查员分配和团队指标。

📖 中文导读:从Graphite和GitHub指南中提炼的pull request最佳实践。当创建pull requests并与graphite-workflow技能一起使用以确保它们遵循大小指南、包含适当的上下文并促进高效的审查时使用。涵盖PR堆叠、描述模板、审查员分配和团队指标。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: pr-guidelines description: Pull request best practices distilled from Graphite and GitHub guides. Use when creating pull requests in conjunction with the graphite-workflow skill to ensure they follow size guidelines, include proper context, and facilitate efficient reviews. Covers PR stacking, description templates, reviewer assignment, and team metrics. user_invocable: true

Pull Request Best Practices

Overview

This skill provides distilled best practices for creating effective pull requests. Smaller, well-structured PRs lead to faster reviews, fewer bugs, and more efficient collaboration.

Key insight: Teams with ~50 line PR averages ship 40% more code than teams with 200+ line PRs.

When to Use This Skill

Use this guidance when:

  • Creating a new pull request
  • Reviewing a pull request for structure and completeness
  • Planning a large feature that needs to be split into multiple PRs
  • Establishing team PR guidelines and metrics

PR Size Guidelines

Metric Ideal Acceptable Flag for Review
Lines changed ~50 < 200 > 500
Files affected 1-3 < 10 > 10
Scope Single task Related changes Multiple unrelated features

Keep PRs atomic - Each PR should accomplish one clear goal and be mergeable independently.

Break Down Tasks Early

During planning, if a feature will require hundreds of lines or touch many files, break it down:

Example: User authentication

  • PR 1: Backend API logic
  • PR 2: User interface components
  • PR 3: Refactoring and test updates

Each change addresses one piece and keeps PRs digestible.

Before Submitting

Run through this checklist:

  • Self-review: Run through changes and trim unnecessary code
  • Build and test: Catch obvious errors before others see them
  • Check scope: Ensure you're only addressing one task
  • Verify size: Under 200 lines is ideal

Ask Yourself

  • Are there unrelated changes that should be split?
  • Have I kept the focus on a single task?
  • Can I add explanations to help reviewers understand context?

PR Description Template

## Summary

<!-- Brief description of what this PR does -->

## Related Issues

<!-- Link to related issues: Fixes #123, Closes #456 -->

## Type of Change

<!-- Mark the appropriate option with an "x" -->

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Data addition (film, developer, or recipe entries)

## Changes Made

<!-- List the key changes in this PR -->

-
-
-

## Testing

<!-- Describe how you tested your changes -->

- [ ] I have run `bun run test` and all checks pass
- [ ] I have added tests that prove my fix/feature works
- [ ] I have tested manually in the development environment

## Checklist

- [ ] My code follows the project's code style
- [ ] I have formatted my code with `bun run format`
- [ ] I have made corresponding changes to documentation (if applicable)
- [ ] My changes generate no new warnings
- [ ] I have checked that there are no circular dependencies between packages

## Screenshots

<!-- If applicable, add screenshots to demonstrate the change -->

## Additional Notes

<!-- Any additional context or information for reviewers -->

Breaking Changes

Explicitly call out:

  • API changes affecting downstream consumers
  • Database migrations requiring coordination
  • Configuration changes
  • Compatibility considerations

Provide Context for Reviewers

  • Write clear titles and descriptions
  • Link to tracking issues or previous conversations
  • Share the type of feedback needed (quick look vs. deeper critique)
  • For multi-file PRs, guide reviewers on where to start
  • Include before/after screenshots for UI changes

PR Stacking

For large features, use stacked PRs to maintain reviewability:

main <- PR 1: Core infrastructure/base changes
     <- PR 2: Feature components building on base
     <- PR 3: Integration/UI changes

Each PR in the stack should remain independently reviewable (< 200 lines).

Benefits:

  • Establish core infrastructure first
  • Subsequent PRs build on those changes
  • Parallel progress without blocking
  • Easier to pinpoint and assign reviewers by domain

Assigning Reviewers

Thoughtfully assign based on expertise:

Change Type Reviewer
Core infrastructure Senior engineers/DevOps
UI updates UX designers + frontend engineers
Security changes Security team (auth/crypto/access)
Domain logic Owners of affected components

Small PRs make precise reviewer assignments easier.

When PRs Must Be Large

If a large PR is unavoidable:

  • Communicate early: Notify the team a large PR is coming
  • Label it: Use tags like large or needs extended review
  • Provide detailed breakdown: Bullet points for each major change
  • Consider PR stacking: Keep each PR under 200 lines while maintaining dependencies

Common Pitfalls

Pitfall Solution
Feature creep - bundling unrelated changes One task per PR, use stacking
Context vacuum - sparse descriptions Use template, link to issues
Review bottlenecks - waiting on one person Add multiple reviewers with domain expertise
Unintentional dependencies - breaking other features Consider downstream impacts, note breaking changes
Knowledge silos - narrow technical review Include diverse perspectives (UX, security, ops)

Automation

Let tools catch shallow issues so humans can focus on logic and architecture:

  • Linting and formatting (run before PR)
  • Type checking
  • Unit tests
  • Security scans (dependency review, code scanning)

Commands:

# Run verification before considering done
bun run test

Team Metrics to Track

Monitor these to identify workflow bottlenecks:

  • Time to first review - Target: < 1 business day
  • Time from publish to merge - Identify where delays occur
  • PR size distribution - Keep averages low
  • Bugs caught in review - Quality signal

Security Review Checklist

Before submitting, check for security issues:

  • Review the dependency diff for vulnerable dependencies
  • Check the GitHub Advisory Database for context
  • Resolve failing security checks (dependency review, code scanning)
  • Use GitHub Copilot Autofix for security vulnerability suggestions

Handling Review Feedback

  • Respond to every comment - Even if just "acknowledged"
  • Clarify feedback type needed - Quick sanity check or thorough review?
  • Real-time collaboration - For complex context, consider pair programming
  • Ask questions - Frame reviews as conversations, not approvals

Continuous Improvement

Start Tracking the Numbers

  • Monitor review turnaround time
  • Track bugs caught in review
  • Schedule regular retrospectives
  • Survey developers on what works and what's frustrating

Encourage Controlled Experimentation

  • Try variations in review cadence
  • Experiment with PR communication modes
  • Test new tooling integrations
  • Start small, then roll out widely

Promote Knowledge Sharing

  • Make time for informal code reviews
  • Run training workshops on PR best practices
  • Celebrate proactive collaboration publicly