Chapter 6.3 — Pull Requests☕ 15 min read

Pull Requests — Merging Code the Right Way

PR tumhari professionalism ka darpan hai. Self-review karna mat bhoolna!

01What is a Pull Request?

A Pull Request (PR) is a request to merge your branch into another branch — usually main. It is the standard way to integrate code in professional teams.

GitHub calls it "Pull Request", GitLab calls it "Merge Request" — same concept, different names. Both are platform features, NOT Git commands.

A PR contains: code changes (the diff), commit history, description, comments, review status, and CI checks. It is a complete record of how and why code entered the project.

Why PRs matter: code review catches bugs, CI/CD validates builds, documentation provides context, discussion enables collaboration, and safe integration prevents broken main branches.

Without PRs: everyone pushes directly to main = chaos, bugs, no accountability, no review, no CI validation. One bad push can break production for everyone.

# The PR Workflow
# 1. Create a branch
git checkout -b feature/login

# 2. Make commits
git commit -m "feat: add login"

# 3. Push to remote
git push -u origin feature/login

# 4. Create Pull Request on GitHub
# (via GitHub UI or `gh pr create`)

# 5. Team reviews, CI runs, changes requested

# 6. Address feedback with new commits
git commit -m "fix: address review feedback"
git push origin feature/login
# PR updates automatically!

# 7. PR approved + CI green → Merge
# (via GitHub UI or `gh pr merge`)

A PR is NOT a Git command. git pull-request does not exist. PRs are a platform feature provided by GitHub, GitLab, and Bitbucket. Git itself only knows about branches, commits, and merges. The PR layer sits on top of Git to add review, discussion, and CI integration.

02Anatomy of a Great PR

A great PR has a clear title using conventional commit format. feat: add JWT authentication — not just auth or fixes.

Description template: What (changed), Why (context/business reason), How (implementation approach), Testing (how to verify). Every PR should answer these four questions.

Small scope: under 400 lines changed. If your PR is larger, split it into multiple focused PRs. Reviewers can effectively review 200-400 lines. Beyond that, they just skim and approve.

Self-reviewed: always review your own diff before requesting others. Click "Files changed" and read every line.

Up to date: rebased on latest main to avoid merge conflicts during review.

Linked to issue: Closes #42 auto-closes the issue when the PR merges. This keeps your project tracker in sync.

## Good PR Title
feat(auth): add JWT token authentication

## Good PR Description
### What
Adds JWT-based authentication for the login endpoint.

### Why
Current session-based auth does not scale for mobile apps.
See issue #42 for requirements.

### How
- Added `/api/auth/login` endpoint
- Implemented token generation and validation middleware
- Added unit tests for auth flow

### Testing
1. Run `npm test` (all tests pass)
2. Start server: `npm start`
3. POST to `/api/auth/login` with credentials
4. Verify JWT token is returned

Closes #42

💡 Pro Tip: Always self-review your PR before assigning reviewers. Click "Files changed" and read every line as if you are reviewing someone else's code. You will catch 50% of issues before anyone else sees them. This shows respect for your reviewers' time.

03Creating PRs with GitHub CLI

gh is GitHub's official command-line tool for PRs, issues, and more. It lets you create, review, and merge PRs without leaving the terminal.

gh pr create creates a PR from the terminal. Interactive mode prompts for title, body, reviewer. One-liner mode takes flags for everything.

Draft PR: gh pr create --draft marks the PR as work-in-progress. No review is requested, but the PR is visible for early feedback and CI testing.

Check PR status: gh pr status shows your current PRs — created, reviewing, and awaiting review.

Merge PR: gh pr merge --squash (or --merge or --rebase). Choose the merge strategy your team prefers.

# Install GitHub CLI
# Mac: brew install gh
# Windows: winget install GitHub.cli

# Authenticate
gh auth login

# Create PR interactively
gh pr create
# ? Title: feat: add login
# ? Body: (opens editor)
# ? Base branch: main
# ? Reviewers: teammate1, teammate2

# Create PR with flags
gh pr create \
  --title "feat: add JWT authentication" \
  --body "Adds JWT auth. Closes #42" \
  --reviewer teammate1 \
  --base main

# Create draft PR (work in progress)
gh pr create --draft --title "WIP: new dashboard"

# Check PR status
gh pr status

# Merge PR
gh pr merge --squash --delete-branch

04Draft PRs and PR Templates

Draft PR: signals "work in progress, do not review yet". Useful for early feedback, CI testing, or sharing your approach before it is complete.

Convert to ready: when finished, click "Ready for review" on GitHub or run gh pr ready. This notifies reviewers.

PR Templates: .github/PULL_REQUEST_TEMPLATE.md auto-populates the PR description when you create a PR. This enforces consistency across the team.

Multiple templates: store them in .github/PULL_REQUEST_TEMPLATE/bug_fix.md, feature.md, etc. Choose the appropriate template when creating a PR.

Labels: bug, feature, breaking, needs-review, WIP. Help categorize and filter PRs in the repository.

# Create a PR template
mkdir -p .github
cat > .github/PULL_REQUEST_TEMPLATE.md << 'EOF'
## What


## Why


## How


## Testing


## Screenshots (if UI changes)


## Checklist
- [ ] Self-reviewed
- [ ] Tests pass
- [ ] No breaking changes
EOF

# Create draft PR for early feedback
gh pr create --draft --title "WIP: refactor auth module"
# Team sees it is not ready for merge, but can comment

# Mark draft as ready
gh pr ready

# Add labels to PR
gh pr edit 42 --add-label "feature,needs-review"

05Merging a PR: The 3 Options

GitHub offers 3 merge options for PRs. Each produces a different history on main.

1. Create a merge commit: preserves all commits from the branch + adds a merge commit. Full history, but creates a branching graph on main.

2. Squash and merge: ALL PR commits become ONE commit on main. Clean history. Most teams prefer this for feature branches.

3. Rebase and merge: commits are rebased onto main individually. Linear history, no merge commit. Good when each commit is meaningful.

Most teams use "Squash and merge" for feature branches — one clean commit per feature on main. It is easy to read, easy to revert, and keeps the history clean.

Configure default in GitHub: Settings → General → Pull Requests → Allow squash merging.

After merge, delete the branch! Keeps the repo clean. GitHub can auto-delete head branches after merge.

# Option 1: Merge commit (preserves all history)
gh pr merge --merge
# Main gets: feature commit 1, feature commit 2, merge commit

# Option 2: Squash and merge (RECOMMENDED for most teams)
gh pr merge --squash
# Main gets: 1 commit "feat: add login (#42)"
# All WIP/fix commits from the PR are squashed

# Option 3: Rebase and merge (linear history)
gh pr merge --rebase
# Main gets: feature commit 1, feature commit 2 (rebased)
# No merge commit, but granular feature commits

# Auto-delete branch after merge
# GitHub → Settings → General → Automatically delete head branches

# Manual delete
git push origin --delete feature/login  # remote
git branch -d feature/login             # local

The "Squash and Merge" button is the secret to a clean main branch. Feature branches have messy WIP commits ("fix typo", "debug", "pls work"). Squashing combines them into one meaningful commit on main. Reviewers see the full messy history in the PR discussion, but main stays pristine. Configure GitHub to default to squash merge for your team.

Lo kar liya — Key Points:

✅ Pull Request (PR) is a platform feature to request merging your branch, enabling code review and CI checks
✅ A great PR has a clear title (conventional commit format), description (what/why/how), and is small (under 400 lines)
✅ Use gh pr create to create PRs from the terminal and gh pr merge to merge them
✅ Draft PRs signal work-in-progress; convert to ready when finished with gh pr ready
✅ PR templates in .github/PULL_REQUEST_TEMPLATE.md enforce consistent descriptions
✅ Squash and merge combines all PR commits into one clean commit on main — recommended for most teams
✅ Always delete branches after merging to keep the repository clean

Previous6.2 — SSH vs HTTPS Setup 📋 All Chapters Next Chapter6.4 — Code Review Culture →