GitHub 09 🌐 Pull Requests (PRs) Basics and Draft PRs - KandZ

⏱️ Estimated read: 11 min | |

A pull request is the mechanism that turns a private branch into a proposal. It is not a Git operation—Git itself has no concept of a pull request. It is a GitHub feature that wraps a branch in a review workflow: discussion, automated checks, and a merge gate. For a contributor, a pull request is how changes enter the codebase. For a maintainer, it is how changes are evaluated before they become permanent. The draft pull request is a variant of that mechanism, one that says “this is not ready for review yet, but it exists.”

Key point: A pull request proposes merging one branch into another. A draft pull request does the same, but cannot be merged and does not automatically request reviews. The draft is a signal of intent, not a submission for approval.

Why pull requests and drafts exist

The direct-merge problem. Git allows merging a branch locally and pushing the result to main. This works, but it provides no opportunity for review, no record of discussion, and no automated verification before the change becomes part of the shared history. A pull request creates a gate: the code is visible, the tests run, the reviewers comment, and only then does the merge button become available .

The context problem. A commit message can explain what changed, but it cannot host a conversation. A pull request provides a dedicated space for the description of the change, line-by-line comments, and a timeline of decisions. The “Files changed” tab is where reviewers see the diff, the “Conversation” tab is where they discuss it, and the “Checks” tab is where CI reports success or failure .

The work-in-progress problem. Not every branch is ready for review when it is first pushed. A developer may want to open a pull request early to run CI, share the direction of the work, or simply keep track of it in the project’s PR list. A draft pull request allows this without triggering the expectation of a formal review. Code owners are not automatically requested, and the merge button is disabled .

The fork-and-pull model. In open-source projects, contributors often do not have write access to the upstream repository. They fork the repository, push to a branch in their fork, and open a pull request from that fork back to the upstream. The pull request is the only mechanism that bridges the permission gap, allowing a maintainer to review and merge changes from a repository they do not control .

The trade-off. A pull request adds process. For a solo project with no reviewers, it is an extra step. But the moment a second person is involved—or the moment automated checks need to run before a merge—the pull request becomes the only reliable way to enforce quality.

a. Creating a pull request

A pull request is created from the GitHub web interface, the GitHub CLI, or GitHub Desktop. The web interface is the most common path. After pushing a branch, GitHub displays a yellow banner on the repository page with a “Compare & pull request” button. Clicking it opens the pull request creation form .

Title: Fix login button on iOS Safari

Description:
This PR fixes the unresponsive login button on iOS Safari by adding a touch event listener.

Fixes #42

The title should be a concise summary of the change. The description should explain what changed and why. If the pull request resolves an issue, the description can include Fixes #42 or Closes #42, which links the two and automatically closes the issue when the pull request merges .

The form has two dropdowns: the base branch (where the changes will merge into) and the compare branch (the branch containing the changes). For a pull request from a fork, the base branch is in the upstream repository, and the compare branch is in the fork. The “compare across forks” link reveals these options .

b. Draft pull requests

A draft pull request is created by selecting “Create Draft Pull Request” from the dropdown next to the “Create Pull Request” button. The resulting pull request looks like a normal one, but it is marked as a draft in the timeline, and the merge box is disabled with a message that the pull request is still in draft mode .

Draft PR: Work in progress — authentication refactor

- [x] Move token validation to middleware
- [ ] Add refresh token rotation
- [ ] Update tests

Draft pull requests serve three purposes. First, they run CI. The automated checks execute against the draft branch just as they would against a ready pull request, giving early feedback on whether the changes break anything . Second, they signal intent. A draft in the pull request list tells collaborators that work is underway without demanding their attention. Third, they prevent accidental merges. The merge button is locked until the draft is marked as ready .

When the work is complete, the author clicks “Ready for review.” This converts the draft to a normal pull request, triggers any code owner review requests, and enables the merge button if all other requirements are satisfied . A pull request can be converted back to a draft at any time if more work is needed.

c. The pull request tabs and review workflow

A pull request is organized into tabs that serve different functions. The Conversation tab contains the description, the timeline of comments and reviews, and the merge status. The Commits tab shows the individual commits in the branch. The Checks tab shows the results of automated tests, builds, and scans. The Files changed tab is the diff that reviewers read .

Reviewers interact with the diff. They can comment on specific lines, suggest changes that the author can apply with a single click, or submit a formal review. A formal review has three outcomes: Comment (general feedback without approval), Approve (the changes are ready to merge), and Request changes (the author must address the feedback before merging) .

The merge box at the bottom of the Conversation tab summarizes what is blocking the merge. It may say “Review required,” “Checks pending,” or “This branch has conflicts that must be resolved.” The merge button is only enabled when all requirements are met. GitHub provides three merge strategies: merge commit, squash and merge, and rebase and merge. Each produces a different shape of history on the base branch .

Complete Example Session

# ============================================
# PART 1: PUSH A BRANCH
# ============================================

git checkout -b fix-login-ios
# Make changes...
git add .
git commit -m "Add touch listener for iOS login"
git push -u origin fix-login-ios

# ============================================
# PART 2: CREATE A DRAFT PULL REQUEST
# ============================================

# On GitHub, navigate to the repository.
# A yellow banner appears: "fix-login-ios had recent pushes"
# Click "Compare & pull request"
# Select the dropdown next to "Create Pull Request"
# Choose "Create Draft Pull Request"
# Click "Draft Pull Request"

# ============================================
# PART 3: DRAFT PR DESCRIPTION
# ============================================

Title: Fix login button on iOS Safari (WIP)

Description:
This PR adds a touch event listener to the login button to fix the unresponsive issue on iOS Safari.

Currently testing on iOS 17.
Will update when ready for review.

# ============================================
# PART 4: CI RUNS ON DRAFT
# ============================================

# The Checks tab shows test results.
# Even though the PR is a draft, CI runs.
# A failed check is visible in the PR list.

# ============================================
# PART 5: MARK AS READY FOR REVIEW
# ============================================

# Click "Ready for review" at the bottom of the Conversation tab.
# The merge box becomes active if checks pass.
# Code owners are automatically requested to review.

# ============================================
# PART 6: REQUEST A REVIEWER
# ============================================

# In the right sidebar, click "Reviewers" → select a user.
# The reviewer receives a notification.

# ============================================
# PART 7: REVIEWER COMMENTS
# ============================================

# Reviewer opens "Files changed" tab.
# Clicks a line number, writes a comment, clicks "Start a review".
# After reviewing all files, clicks "Submit review".
# Selects "Approve" or "Request changes".

# ============================================
# PART 8: MERGE THE PULL REQUEST
# ============================================

# When all checks pass and reviews are approved:
# Click "Squash and merge" (or "Merge pull request").
# Edit the commit message if needed.
# Click "Confirm squash and merge".

# ============================================
# PART 9: DELETE THE BRANCH
# ============================================

# After merging, GitHub offers a "Delete branch" button.
# Click it to remove the remote branch.
# Locally: git checkout main && git pull

The nine parts trace the lifecycle: push a branch, create a draft, describe the work in progress, let CI run, mark it ready, request a review, receive feedback, merge, and clean up.

Quick Reference

Pull Request Tabs

Tab	Content
Conversation	Description, timeline, reviews, merge status
Commits	Individual commits in the branch
Checks	Automated test and build results
Files changed	The diff for review

Draft PR Behavior

Action	Result
Create draft	Merge disabled, reviews not requested
Mark ready for review	Merge enabled (if checks pass), reviews requested
Convert to draft	Merge disabled again

Merge Strategies

Strategy	Result
Merge commit	Preserves all commits, adds merge point
Squash and merge	Combines all commits into one
Rebase and merge	Replays commits on base, linear history

Best Practices

✅ Do This:

Closes #42
<!-- Link PR to issue for auto-close -->          # ✅

Create Draft Pull Request
<!-- Use draft for work in progress -->           # ✅

Squash and merge
<!-- Keep main history clean for small PRs -->    # ✅

❌ Don’t Do This:

# Merge your own PR without review
<!-- Defeats the purpose of the gate -->          # ❌

# Leave a draft as draft forever
<!-- Signals work that may never finish -->       # ❌

# Push directly to main
<!-- Bypasses all checks and review -->           # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Cannot merge draft	Draft status blocks merge	Click “Ready for review”
Code owner not reviewing	Draft PR does not request reviews	Mark ready for review
Merge button grayed out	Checks failing or reviews missing	Check the merge box for blockers
PR shows unexpected commits	Branch was based on stale main	Rebase or merge main into the branch
Merge creates a messy history	Merge commit strategy used for many small commits	Use squash and merge

Real-World Examples

1. Create a Draft PR

gh pr create --draft --title "WIP: Auth refactor" --body "Testing middleware changes"

2. Mark Ready for Review

Click "Ready for review" on the Conversation tab.

3. Link Issue to PR

Closes #42

4. Request Reviewer

Sidebar → Reviewers → select user

5. Approve a PR

Files changed → Review changes → Approve → Submit review

6. Squash and Merge

Dropdown → Squash and merge → Confirm

7. Create PR from Fork

Compare across forks → base: upstream/main, head: fork/branch

8. Check Merge Status

Merge box shows: "All checks have passed" or blockers

9. Convert Back to Draft

Conversation tab → "Convert to draft"

10. Delete Branch After Merge

Click "Delete branch" on the merged PR page.

Visual

Pull Request Lifecycle

┌──────────────────────────────────────────────┐
│  Push branch to origin                       │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Create PR (draft or ready)                  │
│  Base: main  ←  Compare: feature-branch      │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  CI runs (Checks tab)                        │
│  Reviewers comment (Files changed)           │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  All checks pass, reviews approved?          │
└──────────┬───────────────────────┬───────────┘
           │ YES                   │ NO
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│  Merge enabled       │  │  Fix issues, push    │
│  Click merge         │  │  more commits        │
└──────────────────────┘  └──────────────────────┘

The merge gate is the point of the pull request. It does not open until the requirements are satisfied.

Draft vs Ready

┌──────────────────────────────────────────────┐
│  Draft PR                                    │
│                                              │
│  ├─ Merge: disabled                          │
│  ├─ Reviews: not requested                   │
│  ├─ CI: runs                                 │
│  └─ Visible in PR list                       │
└──────────────────┬───────────────────────────┘
                   │
                   │ Click "Ready for review"
                   ▼
┌──────────────────────────────────────────────┐
│  Ready PR                                    │
│                                              │
│  ├─ Merge: enabled (if checks pass)          │
│  ├─ Reviews: requested from code owners      │
│  ├─ CI: runs                                 │
│  └─ Visible in PR list                       │
└──────────────────────────────────────────────┘

The draft is a signal. Marking ready is the transition to formal review.

Summary

Item	Value
PR purpose	Propose merging one branch into another
PR tabs	Conversation, Commits, Checks, Files changed
Draft PR	Cannot merge, no auto review requests
Mark ready	Enables merge, requests code owner reviews
Link issue	`Closes #42` in description
Review outcomes	Comment, Approve, Request changes
Merge strategies	Merge commit, Squash, Rebase
From fork	Base: upstream, Head: fork branch

Key takeaways:

A pull request is a proposal, not a push. It opens a review workflow that a direct merge bypasses. The merge button is the final step, gated by checks and approvals .
Draft pull requests are for work in progress. They run CI and appear in the PR list, but they cannot be merged and do not request reviews. Marking ready is the transition to formal review .
The Files changed tab is where reviewers work. Comments on specific lines, suggested changes, and formal reviews all happen against the diff .
The merge box reports blockers. Required reviews, pending checks, and merge conflicts all appear there. The merge button is only enabled when the box is clear.
Squash and merge keeps history clean. For a pull request with many small commits, squashing combines them into one commit on the base branch .
Fork-based pull requests are the open-source standard. The base branch is in the upstream repository, and the compare branch is in the fork. “Compare across forks” is the option that enables this .

Remember: A pull request is the gate between a branch and main. It exists to catch problems before they become permanent, to record the discussion of why a change was made, and to enforce the checks that automated systems provide. A draft pull request is the same gate, left open for work that is not yet ready. Use it to signal intent, not to request approval.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!