Draft Pull Requests

Draft pull requests let you share work-in-progress code without requesting a full review. They're perfect for getting early feedback, showing your approach, or collaborating on incomplete features.

What is a Draft PR?

A draft PR is marked as "not ready for review":

┌────────────────────────────────────────────┐
│  🟡 Draft                                  │
│  This pull request is still a work in     │
│  progress                                  │
└────────────────────────────────────────────┘

Draft PRs:

• Can't be merged accidentally
• Don't send review requests
• Run CI checks (if configured)
• Can receive comments and feedback

When to Use Draft PRs

Scenario	Use Draft?
Early feedback on approach	✅
Work in progress	✅
Blocked by dependency	✅
Sharing for collaboration	✅
Running CI before ready	✅
Ready for full review	❌ Use regular PR
Quick, simple fix	❌ Use regular PR

Creating a Draft PR

From GitHub Web UI

1. Push your branch
2. Click "Compare & pull request"
3. Click the arrow on "Create pull request"
4. Select "Create draft pull request"

From GitHub CLI

# Create draft PR
gh pr create --draft

# Create with details
gh pr create --draft --title "WIP: Add user auth" --body "Early implementation"

Converting Existing PR to Draft

1. Go to the PR
2. Click "Convert to draft" in the sidebar

Note: This removes existing review requests.

Draft PR Best Practices

Clear Titles

Indicate work-in-progress status:

WIP: Add user authentication
[Draft] Implement caching layer
🚧 Refactor database queries

Describe What You Need

Be specific about what feedback you want:

## Status
This is a work in progress. I'm looking for:

- [ ] Feedback on the overall approach
- [ ] Suggestions for the API design
- [ ] Input on error handling strategy

## What's Done
- Basic authentication flow
- Password hashing

## What's Not Done
- Session management
- Remember me functionality
- Tests

Use Task Lists

Track progress within the PR:

## Progress
- [x] Create user model
- [x] Add password hashing
- [ ] Implement JWT tokens
- [ ] Add refresh tokens
- [ ] Write tests
- [ ] Add documentation

Update Regularly

Keep the PR description current:

• Check off completed tasks
• Note blockers or questions
• Summarize recent changes

Working with Draft PRs

Getting Feedback

Even as a draft, you can:

• Request informal reviews from teammates
• @ mention specific people for input
• Ask questions in comments

Running CI

Most CI systems run on drafts:

• Catch build issues early
• Run tests as you develop
• Check code coverage

Collaborating

Multiple people can push to a draft:

# Teammate adds to your branch
git checkout -b feature origin/feature
# Make changes
git push origin feature

Converting to Ready

When your work is complete:

From Web UI

1. Scroll to bottom of PR
2. Click "Ready for review"
3. This sends notifications to reviewers

From CLI

gh pr ready

Draft PR Workflow

┌─────────────────────────────────────────────────┐
│                    DRAFT PR                      │
├─────────────────────────────────────────────────┤
│                                                  │
│  1. Create draft PR early                        │
│         ↓                                        │
│  2. Push commits as you work                     │
│         ↓                                        │
│  3. Get informal feedback                        │
│         ↓                                        │
│  4. Watch CI results                             │
│         ↓                                        │
│  5. Complete task list                           │
│         ↓                                        │
│  6. Self-review                                  │
│         ↓                                        │
│  7. Mark as "Ready for review"                   │
│         ↓                                        │
│  8. Formal code review                           │
│         ↓                                        │
│  9. Merge                                        │
│                                                  │
└─────────────────────────────────────────────────┘

Draft PRs vs Branches

Why open a draft PR instead of just working on a branch?

Draft PR	Branch Only
Visible progress	Hidden work
Early feedback possible	No review until ready
CI runs automatically	Manual CI trigger
Discussion in one place	Scattered communication
Clear intent to merge	Unknown destination

Common Patterns

Stacked PRs

Use drafts for dependent PRs:

PR 3: Add UI components (Draft - depends on PR 2)
  ↓
PR 2: Add API endpoints (Draft - depends on PR 1)
  ↓
PR 1: Add database models (Ready for review)

Long-Running Features

For features that take weeks:

## Feature: New Dashboard

This is a multi-week effort. Current status:

### Week 1 (Complete)
- [x] Data models
- [x] API design

### Week 2 (In Progress)
- [x] Basic API endpoints
- [ ] Authentication integration

### Week 3 (Planned)
- [ ] Frontend components
- [ ] E2E tests

RFC/Proposal PRs

Sometimes you want feedback before coding:

## RFC: New Caching Strategy

This is a proposal PR. The code is a rough prototype.
I'm looking for feedback on the approach before investing more time.

### Proposed Approach
...

### Alternatives Considered
...

### Questions for Reviewers
1. Does this approach make sense?
2. Any concerns about the cache invalidation strategy?
3. Should we use Redis or Memcached?

Summary

• Draft PRs indicate work-in-progress
• Can't be merged accidentally
• Great for early feedback and collaboration
• Use clear titles and descriptions
• Include task lists to track progress
• Convert to "Ready for review" when complete
• CI usually runs on drafts
• Better than working in silence on branches

In the next module, we'll explore different collaboration workflows.