Pull Requests: the complete guide 🔀

A Pull Request (PR) is a formal proposal to merge changes from one branch into another. It is the cornerstone tool of collaborative development.

What is a Pull Request in plain English

Imagine: you’ve been working on a new feature in a separate branch and you’re done. Now you want those changes to land in the main branch (main). Merging it in directly isn’t great practice — no one has reviewed your work.

A Pull Request is:
1. Showing the team what you built
2. Asking for a review before merging
3. Getting feedback and discussing design decisions
4. Leaving a permanent record of decisions made

Your branch:  feature/login ──●──●──●──●
                                        ↓ Pull Request
Main:         main ──────────────────────●  ← merge

PR vs committing directly to main

In most professional teams, committing directly to main is forbidden.

How to create a Pull Request

Step 1: Push your branch

git push origin feature/my-feature

In GitHub Desktop: click Push origin (or Publish branch on the first push).

Step 2: Open GitHub

After pushing, GitHub will show a yellow banner:

“feature/my-feature had recent pushes — Compare & pull request“

Click it, or go to Pull requests → New pull request.

Step 3: Select branches

Make sure the direction is correct:

base: main  ←  compare: feature/my-feature
  ↑ destination              ↑ source

Step 4: Fill in the PR details

• Title — short and specific
• Description — detailed (see the template below)

Step 5: Create the PR

Click Create pull request.

How to write a good PR description

Bad description ❌

fix bug

update

Good description ✅

## What was done
Added validation for the `description` field when creating a task.
The API now returns a proper response instead of a 500 error.

## Why
Bug from ticket #47: a task without a description was crashing the service.

## How to verify
1. Open POST /api/tasks
2. Send a request without the description field
3. Confirm the response is 200 with description: "No description"

## Notes
Using a default value for now. Later we can make description
nullable at the database level.

PR description template

## What was done
[1–3 sentences describing the change]

## Why
[Context: the problem or task]

## How to verify
1. [Concrete step]
2. [Concrete step]

## Screenshots / Demo
[If there are visual changes]

Anatomy of a PR page

Conversation tab

The main discussion feed. Reviewer comments, event history (pushes, reviews, assignments).

Commits tab

All commits that will be included in the merge. Each commit links to its diff.

Files Changed tab ⭐

The primary place for code review! A line-by-line diff of all changed files.
You can add inline comments to specific lines.

How to update a PR

After creating a PR, you don’t need to create a new one if something needs to change.

Just make a new commit in the same branch and push — the PR updates automatically:

PR #12: feat: add login form

Commits:
● feat: create login form          ← initial push
● fix: fix validation per review   ← after review feedback
● docs: add comments as requested  ← more revisions

PR statuses

Three merge strategies

Merge commit (default)

main: ──●──────────────────────●── 
                                ↑
feature:    ──●──●──●──────────/ (merge commit)

Full history — all commits from the feature branch are visible. Recommended for learning.

Squash and merge

main: ──●──────────────────────●── 
                                ↑
                          One commit containing everything

All commits from the feature branch are “squashed” into one. Clean history, but you lose granularity.

Rebase and merge

main: ──●──●──●──●──────────── 
              ↑↑↑
        Feature commits "replanted" onto main

Linear history with no merge commit. For advanced users.

After merge: delete the branch

GitHub will immediately offer Delete branch. Accept it — the branch has served its purpose.

To delete locally:

git branch -d feature/my-feature

In GitHub Desktop, switch to main, then go to Branch → Delete.

PRs for different scenarios

Typical PR within a team

You are a repo member → push a branch → open a PR → get a review → merge.

PR from a fork (Open Source)

You are not a member → fork → clone the fork → push to your fork → open a PR from the fork to the original.

See the article GitHub Fork: contributing to someone else’s project for details.

Useful PR features

Draft PR — open a PR early, marked as “in progress.” Colleagues can see what you’re working on and give early feedback. When ready, click “Ready for review.”

Reviewers — assign specific people to review. They’ll get a notification.

Assignees — who is responsible for the PR (usually the author).

Labels — tags: bug, feature, documentation, help wanted.

Linked Issues — write Closes #42 in the description and the PR will automatically close the Issue on merge.

Why PRs matter for your career

Knowing how to write good PRs is one of the most important professional skills.

Employers look at:
- Your PR descriptions in open-source projects
- How you respond to review feedback
- The cleanliness of your commit history

A good PR shows that you think not just about the code, but about the team.