Pull Requests — Getting Work Reviewed

The process of proposing changes, getting feedback, and merging approved work into the main project.

What is a pull request?

A pull request (PR) is like submitting a draft report for review before it gets published. You have been working on your section. Before it goes into the final document, you send it to your editor (or team) for feedback. They can approve it, suggest changes, or ask questions. Only after approval does it become part of the official version.

A pull request (often shortened to PR) is a formal request to merge your branch into another branch (usually develop or main). It includes:

Your changes

Every file you added, modified, or deleted — shown side by side with the original so reviewers can see exactly what changed.

A description

An explanation of what you did and why. Good PRs include context, screenshots, and testing notes.

Discussion thread

Reviewers can leave comments on specific lines of code, ask questions, or suggest improvements.

Status checks

Automated tests that run to verify your changes do not break anything. These are shown as green checkmarks or red crosses.

The PR lifecycle

sequenceDiagram participant Dev as Developer participant GH as GitHub participant Rev as Reviewer participant CI as Automated Tests Dev->>GH: Push branch & open PR GH->>CI: Run automated tests GH->>Rev: Notify: "New PR for review" CI-->>GH: Tests pass (or fail) Rev->>GH: Review changes alt Changes needed Rev->>GH: Request changes + comments GH->>Dev: Notify: "Changes requested" Dev->>GH: Push fixes GH->>CI: Re-run tests CI-->>GH: Tests pass Rev->>GH: Approve else Looks good Rev->>GH: Approve end Dev->>GH: Merge PR GH->>GH: Branch merged into develop

The complete lifecycle of a pull request: open it, get it tested and reviewed, address any feedback, get approval, and merge.

What reviewers look for

When someone reviews a PR, they are checking several things:

Does it work?

The automated tests pass, and the feature does what it claims to do.

Is it safe?

No security issues, no accidentally deleted files, no broken functionality.

Is it clean?

The code is readable, well-organized, and follows the project's conventions.

Is it complete?

Nothing is missing — no half-implemented features or TODO comments left behind.

PR status explained

When you look at a PR on GitHub, you will see status indicators. Here is what they mean:

Status What it means Action needed
Open The PR exists and is waiting for review or work Reviewer needs to look at it
Draft Work in progress — not ready for review yet Developer is still working
Changes requested Reviewer found issues that need fixing Developer needs to address feedback
Approved Reviewer is happy with the changes Ready to merge
Merged Changes have been incorporated into the target branch Done! Branch can be deleted
Closed PR was abandoned without merging Nothing — the work was discarded or redone differently

What merging means

Merging is like accepting the final draft into the published document. The edited chapter has been reviewed, corrections applied, and the editor signs off. Now it officially becomes part of the book. The draft copy is no longer needed.

When a PR is merged, Git takes all the changes from your feature branch and applies them to the target branch (usually develop). After merging:

  • Your changes are now part of develop
  • The feature branch is typically deleted (it served its purpose)
  • Any worktree associated with that branch can also be removed

The merging flow

flowchart TB A["Feature branch\nwith your changes"] --> B{"PR approved?"} B -->|Yes| C["Merge into develop"] B -->|No| D["Address feedback"] D --> A C --> E["Delete feature branch"] E --> F["Delete worktree\n(if used)"] F --> G["Changes are live\non develop"] style A fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style B fill:#141a2e,stroke:#ffab40,color:#e0e6f0 style C fill:#1e2a4a,stroke:#00e676,color:#e0e6f0 style D fill:#1e2a4a,stroke:#ff5252,color:#e0e6f0 style E fill:#1e2a4a,stroke:#8892a8,color:#e0e6f0 style F fill:#1e2a4a,stroke:#8892a8,color:#e0e6f0 style G fill:#1e2a4a,stroke:#00e676,color:#e0e6f0

After approval, the feature branch is merged into develop and then cleaned up.

Common things you might hear

"Can you review my PR?"
The developer is asking someone to look at their proposed changes and approve or request changes.
"The PR has merge conflicts."
The branch has changes that overlap with other recent changes. The developer needs to reconcile them before merging. This is routine.
"CI is failing on the PR."
The automated tests found a problem. The developer needs to fix it before the PR can be merged. CI stands for Continuous Integration (the automated testing system).
"I'll squash and merge."
Instead of merging all individual commits, the developer will combine them into one clean commit. This keeps the history tidy.

Key takeaways

Remember:
  • A PR is a formal request to merge your work into the main project.
  • PRs include code changes, a description, discussion, and test results.
  • Work goes through review and approval before it is merged.
  • After merging, the feature branch and worktree are cleaned up.