Creating a Pull Request

A pull request is a formal proposal to merge changes from one branch into another. It is the primary mechanism for collaboration on GitHub — the place where code is proposed, discussed, reviewed, and approved before it becomes part of the main codebase. Understanding how to create a pull request well is one of the most practical skills in working with GitHub.

What Triggers a Pull Request

A pull request requires two things: a branch with commits that the target branch does not have, and a desire to merge that work in. The branch can live in:

• The same repository — common for teams where everyone has write access. You push a feature branch and open a PR to main.
• A fork — common for open source contributions. You push to your fork and open a PR to the upstream repository's main.

In both cases, the pull request process on GitHub is identical.

Before Opening a Pull Request

Before creating the PR, make sure the groundwork is in place:

# 1. Ensure you are on your feature branch
git switch feature/dark-mode

# 2. Make sure all changes are committed
git status
# nothing to commit, working tree clean

# 3. Pull in any recent changes from main to reduce conflicts
git fetch origin
git merge origin/main

# 4. Push your branch to the remote
git push -u origin feature/dark-mode

After pushing, GitHub detects the new branch and displays a yellow banner on the repository page: "feature/dark-mode had recent pushes — Compare & pull request." Clicking this banner takes you directly to the PR creation form.

The Pull Request Form

The PR creation form has several fields:

Base and Compare Branches

At the top of the form, two dropdowns define the direction of the merge:

• Base — the branch you want to merge into (usually main).
• Compare — your branch with the changes.

If you are opening a PR from a fork, GitHub also lets you select the base repository — the upstream project — and the compare repository — your fork.

Title

The title is the first thing reviewers see. Write it as a concise, imperative statement of what the PR does:

Add dark mode toggle to settings panel
Fix null pointer exception in authentication middleware
Update README with installation instructions

Avoid vague titles like "Updates" or "Fix stuff" — they give reviewers no information before they open the PR.

Description

The description is where you give reviewers the context they need to evaluate your changes. A well-written PR description typically covers:

• What — a summary of the changes made.
• Why — the motivation or problem being solved.
• How — a brief explanation of the approach taken, especially for non-obvious implementation choices.
• Testing — how you verified the changes work.
• Screenshots — for UI changes, before and after screenshots dramatically speed up visual review.

A template for writing good PR descriptions:

## What
Added a dark mode toggle to the user settings panel.

## Why
Users requested this in issue #47. The current light-only interface
causes eye strain in low-light environments.

## How
- Added a `theme` field to the user preferences model.
- Stored the preference in localStorage for persistence across sessions.
- Applied the theme class at the root element level so all components
  respond automatically.

## Testing
- Manually tested toggle in Chrome, Firefox, and Safari.
- All existing tests pass.

Closes #47

Linking Issues

GitHub automatically closes linked issues when the PR is merged if you use specific keywords in the description:

Closes #47
Fixes #23
Resolves #89

You can link multiple issues:

Closes #47, fixes #23

When the PR merges into the default branch, GitHub closes the linked issues and creates a cross-reference between them.

Reviewers

Request specific people to review the PR using the Reviewers field in the right sidebar. Requested reviewers receive a notification and the PR appears in their review queue. In repositories with branch protection rules, a minimum number of approvals may be required before merging is possible.

Assignees

The Assignee field indicates who is responsible for the PR — usually the person who created it, but sometimes the person responsible for seeing it through review and merging.

Labels

Labels categorise PRs for filtering and organisation. Common labels include bug, enhancement, documentation, breaking change, and needs review. Labels are defined per repository — you or a maintainer creates them in the repository settings.

Milestone

Linking a PR to a milestone groups it with other PRs and issues that belong to the same release or sprint. The milestone's progress bar updates as linked items are closed.

Opening the Pull Request

Once the form is filled in, click Create pull request. GitHub:

1. Creates the PR and assigns it a number (e.g. #42).
2. Notifies all requested reviewers.
3. Notifies anyone watching the repository.
4. Runs any configured status checks (CI tests, linting, etc.).
5. Checks whether the branch merges cleanly into the base branch.

The PR page then becomes the central hub for all discussion, review, and activity related to that change.

Draft Pull Requests

If the work is not yet ready for review — you want feedback on the approach, or the implementation is still in progress — open a draft pull request instead:

1. Click the dropdown arrow next to Create pull request.
2. Select Create draft pull request.

Draft PRs:

• Are clearly labelled as drafts in the PR list.
• Cannot be merged until converted to ready.
• Still trigger notifications and can receive comments.
• Are visible to the whole team, which is useful for visibility and early feedback.

Convert a draft to ready when the work is complete:

1. Scroll to the bottom of the PR page.
2. Click Ready for review.

Draft PRs are particularly useful for long-running features where you want teammates to follow progress without being prompted for a formal review.

PRs Between Branches in the Same Repository

Forking is not required to open a pull request. If you and a collaborator both have write access to the same repository, you can:

1. Create a branch directly in the repository.
2. Push it.
3. Open a PR from that branch to main.

No fork needed. This is the standard flow for teams working in a shared repository — it provides the same review and discussion benefits as fork-based PRs without the overhead of managing a fork.

What Happens After Opening

Once the PR is open, the branch remains active. You can:

• Push additional commits at any time — the PR updates automatically.
• Respond to review comments by making changes and pushing.
• Add co-authors if multiple people contributed.
• Reference the PR from other issues, PRs, or commits using #<number>.

The PR stays open until it is either merged or closed (without merging). If it is closed without merging, it can be reopened later — no work is lost.

A Good Pull Request at a Glance

The most important item on this list is size. Small, focused pull requests are reviewed faster, merged faster, and produce fewer conflicts than large ones. If a PR is getting long, it almost always should be broken into smaller ones.