Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 17 of 30

Issues and pull requests on GitHub

Track work with GitHub issues, propose changes with pull requests, understand merge options, and see which Git commands sit behind each step of the process.

14 minRemotes and GitHubUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonDescribe the issue-to-pull-request cycle, prepare a branch that is ready for review, and explain the three ways a pull request can be merged.

What you can do after this lesson

You will understand how a team turns an idea into a merged change on GitHub, and which parts of that journey are plain Git. Clicking buttons on GitHub is described in words (the labels change over time; check docs.github.com). The Git commands underneath were run and verified against a local bare repository.

Issues: write the problem down

An issue is a numbered thread attached to a repository. People use issues for bug reports, feature ideas, questions and tasks. Each has a title, a description in Markdown, comments, and optional labels (such as "bug"), assignees and milestones. Numbers are per repository, so #12 means the twelfth issue or pull request there.

A good bug report says what you did, what you expected, what happened, and your environment. A good task issue says what "done" means. Writing the problem before the code makes later discussions easier, and gives pull requests something to refer to.

The pull request cycle

A pull request (PR) asks the project to merge your branch into another, usually main. The cycle has the same shape almost everywhere:

  1. Create a branch for one change.
  2. Commit your work to it.
  3. Push the branch to GitHub.
  4. Open the pull request on the website, with a title and description.
  5. Teammates review, comment and request changes. You push more commits to the same branch, and the PR updates automatically.
  6. Automated checks may run.
  7. When approved, someone merges the PR.
  8. Delete the branch and update your local main.

Only steps 4 to 7 are GitHub features. The rest is Git.

The Git side

Branch, commit and push, exactly as in earlier lessons:

bash
git switch -c fix-typo-in-readme
git commit -am "Describe the project"
git commit -am "Add usage line"
git push -u origin fix-typo-in-readme
text
To /home/you/pr/origin.git
 * [new branch]      fix-typo-in-readme -> fix-typo-in-readme
branch 'fix-typo-in-readme' set up to track 'origin/fix-typo-in-readme'.

(The example output comes from a local bare repository; GitHub prints a similar line, often plus a link to open a PR.) Before opening the PR, review your own change the way a reviewer would. The three-dot form of diff compares your branch to the point where it split from main:

bash
git diff main...fix-typo-in-readme
git log --oneline main..fix-typo-in-readme
text
diff --git a/README.md b/README.md
index 5898adc..fe71daf 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,3 @@
 # Shelf
+A small shelf tracker.
+Run it daily.
ff7d8cb Add usage line
7d82ca0 Describe the project

That is essentially what the PR page's "Files changed" tab shows. Reading it yourself catches stray debug lines and accidental files before anyone else sees them.

Writing a good pull request

The title should say what changed in a sentence, like a commit subject. The description answers: what is this, why, how was it tested, and anything the reviewer should look at. Link the issue. According to GitHub's documentation, writing a keyword such as closes #12 or fixes #12 in the PR description, or in a commit message that reaches the default branch, links the work to the issue and closes it automatically on merge. Check the current documentation for the exact list of keywords and where they work.

Keep PRs small and focused: one logical change. Reviewers cannot hold a thousand changed lines in their heads, and a small PR is easy to revert. If you discover an unrelated problem while working, make a separate branch.

A draft pull request signals "not ready for review yet", useful for early feedback. Pull requests can also request specific reviewers and show the status of automated checks, which the Actions lesson introduces.

Three ways to merge

When the PR is approved, GitHub typically offers three merge styles (a repository's owners can enable or disable each):

Style Result on the target branch Git equivalent
Merge commit All commits kept, plus a merge commit git merge --no-ff
Squash and merge One new commit holding all the changes git merge --squash, then commit
Rebase and merge Commits replayed one by one, no merge commit git rebase, then fast-forward

You can reproduce squash locally to see what it does:

bash
git switch main
git merge --squash fix-typo-in-readme
git commit -m "Improve the README (closes #12)"
git log --oneline --graph
text
Updating 81a4abb..ff7d8cb
Fast-forward
Squash commit -- not updating HEAD
 README.md | 2 ++
 1 file changed, 2 insertions(+)
[main d046f0a] Improve the README (closes #12)
 1 file changed, 2 insertions(+)
* d046f0a Improve the README (closes #12)
* 81a4abb Add README

Two commits became one, and main stays a straight line. Because the branch's original commits are not themselves in main, Git may later regard the branch as unmerged and git branch -d may refuse; a squash-merged branch you are finished with can be removed with -D once you are sure the PR merged. Teams that squash tend to value a tidy main; teams that keep individual commits value the detailed history. Neither is wrong.

After the merge

Delete the branch on GitHub (there is a button), then tidy locally:

bash
git switch main
git pull
git fetch --prune

Use a fresh branch for the next change rather than reusing the old one.

Common mistakes

  • Opening a PR from main of your own copy. Use a topic branch so main stays clean.
  • Mixing unrelated changes in one PR. Reviewers cannot approve half of it.
  • Empty descriptions. Reviewers need context.
  • Pushing fixes as a new PR instead of new commits on the branch. Review comments belong on one PR.
  • Merging your own PR without review on a team that requires one. Respect the project's rules.

Exercise

  1. In a practice repository with a local bare remote, create docs-update, make two commits and push it.
  2. Look at the change as a reviewer would, with git diff main...docs-update.
  3. Merge it into main with --squash and commit. Compare the log to a --no-ff merge made on a copy.
Show one possible answer
bash
git switch -c docs-update
echo "one" >> README.md && git commit -am "Docs one"
echo "two" >> README.md && git commit -am "Docs two"
git push -u origin docs-update
git diff main...docs-update
git switch main
git merge --squash docs-update
git commit -m "Update docs"
git log --oneline --graph

The log shows one new commit on main. With --no-ff you would see two commits plus a merge commit.

Next: Forks and code review on GitHub.

Key points

  • An issue is a discussion thread for a bug, task or idea; a pull request (PR) is a proposal to merge one branch into another, with discussion and review.
  • A PR is not a Git command: you push a branch with git push, then open the PR on GitHub's website.
  • Small, focused PRs with a clear description are reviewed faster and more safely.
  • GitHub can merge a PR with a merge commit, a squash into one commit, or a rebase; teams choose one style.
  • Writing closes #12 in a PR description can link the PR to issue 12 and close it on merge, as described in GitHub's documentation.

Check yourself

1. What is a pull request?
2. Before you can open a pull request from your branch, what must be true?
3. Which merge style turns all of a PR's commits into one commit on the target branch?
4. What is the best size for a pull request?