Stacked Pull Requests
Overview
Stacked PRs are dependent pull requests where each PR builds on the previous one. Use this pattern for complex features that need logical separation and parallel review.
When to Use
✅ Use Stacked PRs When:
-
User explicitly requests "stacked PRs" or "dependent PRs"
-
Large feature needs to be split into logical phases
-
Each phase has clear dependencies on previous phases
-
User is comfortable with rebase workflows
❌ Use Main-Based PRs When (Default):
-
Features are independent
-
Simple bug fixes or enhancements
-
Multiple agents working in parallel
-
User doesn't specify preference
DEFAULT: Always prefer main-based PRs unless user explicitly requests stacking.
Branch Naming Convention
Use sequential numbering to show dependencies:
feature/001-base-authentication # PR-001 (base) feature/002-user-profile # PR-002 (depends on 001) feature/003-admin-panel # PR-003 (depends on 002)
Alternative patterns:
auth/01-foundation auth/02-user-flow auth/03-admin-features
Creating Stacked PRs
Step 1: Create Base PR (PR-001)
Start from main
git checkout main git pull origin main
Create base branch
git checkout -b feature/001-base-auth
Implement base functionality
... work ...
Push and create PR
git push -u origin feature/001-base-auth
Create PR in GitHub/GitLab
Title: "[1/3] Base authentication foundation"
Base: main
Description: Include stack overview (see template below)
Step 2: Create Dependent PR (PR-002)
CRITICAL: Base on previous feature branch, NOT main
Start from PR-001's branch
git checkout feature/001-base-auth git pull origin feature/001-base-auth
Create dependent branch
git checkout -b feature/002-user-profile
Implement dependent functionality
... work ...
Push and create PR
git push -u origin feature/002-user-profile
Create PR in GitHub/GitLab
Title: "[2/3] User profile management"
Base: feature/001-base-auth ← NOT main!
Description: "Depends on PR #123"
Step 3: Create Final PR (PR-003)
Start from PR-002's branch
git checkout feature/002-user-profile git pull origin feature/002-user-profile
Create final branch
git checkout -b feature/003-admin-panel
Implement final functionality
... work ...
Push and create PR
git push -u origin feature/003-admin-panel
Create PR in GitHub/GitLab
Title: "[3/3] Admin panel with full auth"
Base: feature/002-user-profile ← NOT main!
Description: "Depends on PR #124"
PR Description Template
Use this template for stacked PRs:
This PR
[Brief description of changes in THIS PR only]
Depends On
- PR #123 (feature/001-base-auth) - Must merge first
- Builds on top of authentication foundation
Stack Overview
- PR #123: Base authentication (feature/001-base-auth) ← MERGE FIRST
- PR #124: User profile (feature/002-user-profile) ← THIS PR
- PR #125: Admin panel (feature/003-admin-panel) - Coming next
Review Guidance
To see ONLY this PR's changes:
git diff feature/001-base-auth...feature/002-user-profile
Or on GitHub: Compare feature/002-user-profile...feature/001-base-auth
(three dots)
Testing
- Tested in combination with PR #123
- Includes tests for user profile functionality
- Integration tests pass with base auth layer
## Managing Rebase Chains
### When Base PR Changes (Review Feedback)
If PR-001 gets updated, rebase dependent PRs:
```bash
# Update PR-001 (base)
git checkout feature/001-base-auth
git pull origin feature/001-base-auth
# Rebase PR-002 on updated base
git checkout feature/002-user-profile
git rebase feature/001-base-auth
git push --force-with-lease origin feature/002-user-profile
# Rebase PR-003 on updated PR-002
git checkout feature/003-admin-panel
git rebase feature/002-user-profile
git push --force-with-lease origin feature/003-admin-panel
IMPORTANT: Use --force-with-lease
not --force
for safety
Merge Strategy
Option A: Sequential Merging (Recommended)
- Merge PR-001 to main
- Change PR-002's base to main (GitHub: "Edit" button on PR)
- Merge PR-002 to main
- Change PR-003's base to main
- Merge PR-003 to main
Option B: Keep Stack Until End
- Merge PR-001 to main
- Keep PR-002 based on feature/001 until PR-001 fully merged
- Then rebase PR-002 onto main
- Repeat for PR-003
Common Pitfalls
❌ WRONG: All PRs from main
git checkout main
git checkout -b feature/001-base
# PR: feature/001-base → main
git checkout main # ← WRONG
git checkout -b feature/002-next
# PR: feature/002-next → main # ← WRONG (independent, not stacked)
✅ CORRECT: Each PR from previous
git checkout main
git checkout -b feature/001-base
# PR: feature/001-base → main
git checkout feature/001-base # ← CORRECT
git checkout -b feature/002-next
# PR: feature/002-next → feature/001-base # ← CORRECT (stacked)
Agent Instructions
When delegating stacked PR creation to version-control agent:
Task: Create stacked PR branch structure
Stack Sequence:
1. PR-001: feature/001-base-auth → main (base layer)
2. PR-002: feature/002-user-profile → feature/001-base-auth (depends on 001)
3. PR-003: feature/003-admin-panel → feature/002-user-profile (depends on 002)
Requirements:
- Each branch MUST be based on previous feature branch
- Use sequential numbering (001, 002, 003)
- Include "depends on" notes in commit messages
- Create PR description with stack overview
CRITICAL: PR-002 bases on feature/001-base-auth, NOT on main
CRITICAL: PR-003 bases on feature/002-user-profile, NOT on main
Verification Checklist
Before creating stacked PRs:
- User explicitly requested stacked PRs
- Feature has clear logical phases
- Each phase has dependency on previous
- User understands rebase workflow
- Branch names use sequential numbering
- Each branch created from correct base (previous feature branch)
- PR descriptions include dependency information
- Stack overview documented in each PR
Related Skills
- git-worktrees
- Work on multiple PRs simultaneously
- git-workflow
- General git branching patterns
- code-review
- Review strategies for stacked PRs