Pull Requests, Drafts, Linked Issues, Change Sets, and Collaboration Patterns: Concepts, Architecture, and Mental Model

1. The problem: a branch is not a review decision

Chapter 04 taught you where branches and remotes live. A pushed topic branch proves that commits exist on a hosted repository; it does not say where those commits are intended to land, whether the change is ready for review, which Issue it addresses, what automation ran, or who accepted the risk. A pull request (PR) supplies that hosted collaboration state around Git refs.

The safest mental model is: Git owns commits and refs; GitHub owns the pull-request resource that points at base/head refs and accumulates review, checks, links, policy state, and timeline evidence. When either ref moves, the PR can change even though the PR number stays the same.

2. Base and head: the coordinates of a proposed integration

flowchart TD
  L["Local topic branch
feature/retry-note"] -->|push| H["Head repo/ref
learner/repo:feature/retry-note"]
  B["Base repo/ref
learner/repo:main"] --> PR["Pull request #N"]
  H --> PR
  PR --> D["Commit set + \nFiles changed"]
  PR --> R["Conversation + \nReviews"]
  PR --> C["Checks / \npolicy evidence"]
  PR -->|merge later| B

The base is the repository/branch that would receive the change. The head is the repository/branch containing the proposed commits. In a same-repository PR, base and head repositories are the same and branches differ. In a fork PR, the repositories differ. The words base and head are GitHub collaboration coordinates; they do not create new copies of commits.

GitHub shows a three-dot comparison for pull-request changes. Conceptually, git diff BASE...HEAD compares the merge base (most recent common ancestor) with the head tip, answering “what has this topic introduced since it diverged?” That is different from a two-dot tip-to-tip comparison.

3. A PR also has GitHub-maintained read-only refs

GitHub can expose temporary refs under refs/pull/NUMBER/. head points at the latest PR head commit. When GitHub can create a conflict-free test merge, merge points at a simulated merge result. These refs are useful evidence for CI and diagnostics; they are not branches you should push to.

# Read-only example after you know the pull request number.
git ls-remote origin "refs/pull/17/*"

# Fetch the PR head without changing a hosted branch.
git fetch origin refs/pull/17/head

git show --no-patch --decorate FETCH_HEAD

The simulated merge ref can disappear when a PR has conflicts. Its existence is therefore evidence about GitHub’s current test merge, not a permanent commit promised to remain in your repository history.

4. Pull-request state is hosted collaboration state

Mergeability is computed from current base/head state and repository policy. In the REST API, the mergeable field can temporarily be null while GitHub computes it; a robust diagnostic client does not interpret null as “blocked forever.”

5. Draft versus ready is a communication contract, not a Git rewrite

Converting an open PR between draft and ready changes GitHub metadata. It does not create, delete, or rewrite Git commits. Current GitHub behavior allows the PR author or people with write permission to change this stage. Draft PRs are not mergeable, and CODEOWNERS are not automatically requested until the PR is marked ready.

gh pr view 17 --json number,isDraft,state,headRefName,baseRefName

gh pr ready 17
# Later, when the plan supports conversion back to draft:
gh pr ready 17 --undo

6. Linked Issues, closing keywords, cross-references, and task relationships

A pull request can reference work without owning that work. Mentioning #42 creates context. A supported closing phrase such as Closes #42 can create a development link and—when the PR is merged into the repository’s default branch—close the Issue. GitHub currently ignores those closing keywords when the PR targets a non-default branch. That rule matters in release-branch workflows.

7. Commit set, file diff, conversation, checks, and deployment are different evidence planes

flowchart LR
  PR["PR #N"] --> CM["Commits
which commits are proposed?"]
  PR --> DF["Files changed
what content differs?"]
  PR --> RV["Conversation/reviews
what did humans decide?"]
  PR --> CK["Checks
what automated validations reported?"]
  PR --> IS["Linked Issues
what work is related/resolved?"]
  PR --> DP["Deployment systems
what actually shipped?"]

The commit set answers which head-side commits are part of the proposal relative to the base. The file diff answers what content GitHub believes the proposal introduces. Review conversation captures human feedback and decisions. Checks report automated evidence. Deployment records live elsewhere. Reliable change control keeps those meanings separate.

8. Reviewable change sets and stacked/dependent work

A small PR is not automatically good, and a large PR is not automatically bad. The useful unit is a coherent change that a reviewer can reason about, test, and roll back. When one feature truly depends on another unmerged change, teams sometimes use stacked pull requests: PR B is based on PR A’s branch, then its base is retargeted after A merges. This reduces review size but introduces dependency ordering and base-change complexity.

9. Permission boundaries: author, reviewer, collaborator, maintainer

Creating a PR requires access to a source/head branch you can propose from. Changing draft/ready stage can be done by the author or someone with write permission. Requesting a specific review requires write access, and the requested reviewer must have appropriate repository access. Public repositories can accept comments/reviews broadly, but administrators can restrict who may submit approving or change-requesting reviews. Fork PRs add another trust boundary: the contributor controls the fork/head branch.

10. Read-only inspection before mutation

# Explicit repository removes current-directory ambiguity.
gh pr status -R OWNER/REPO --json number,title,state,isDraft,baseRefName,headRefName,headRefOid

gh pr view 17 -R OWNER/REPO --json   number,title,state,isDraft,baseRefName,baseRefOid,headRefName,headRefOid,   headRepository,commits,files,reviewRequests,reviewDecision,statusCheckRollup,closingIssuesReferences,url

gh pr diff 17 -R OWNER/REPO --name-only

# Current REST API version.
gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   repos/OWNER/REPO/pulls/17   --jq '{number,state,draft,mergeable,base:.base.ref,head:.head.ref,head_sha:.head.sha}'

If the REST response shows mergeable: null, wait briefly and read again; GitHub may still be computing the test merge. Do not “repair” anything based on a temporary null.

11. DevOps connection: the PR is a change-control join point

Pull requests are where four systems meet: Git history, human review, automated validation, and repository policy. Later chapters will deepen reviews, merge methods, rulesets, and Actions, but the operating principle starts here: never infer more than the evidence proves. An approval is not a deployment. A green check is not a merge. A Project “Done” status is not a release.

12. Lesson summary

A PR is a hosted object defined around base/head repositories and refs. Its commits and Files changed derive from Git history; draft/ready, links, reviews, checks, and merge state are GitHub collaboration data. Closing keywords can affect Issue lifecycle only under the documented default-branch conditions. Small, coherent change sets make every later control easier to reason about.

Knowledge check

Authoritative references

• About pull requests
• Branches and pull-request comparisons
• Comparing commits
• Changing the stage of a pull request
• Linking a pull request to an issue
• Requesting a pull request review
• Approving workflow runs from forks
• gh pr
• gh pr view
• REST API endpoints for pull requests
• REST API versions