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:
- Create a branch for one change.
- Commit your work to it.
- Push the branch to GitHub.
- Open the pull request on the website, with a title and description.
- Teammates review, comment and request changes. You push more commits to the same branch, and the PR updates automatically.
- Automated checks may run.
- When approved, someone merges the PR.
- 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:
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-readmeTo /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:
git diff main...fix-typo-in-readme
git log --oneline main..fix-typo-in-readmediff --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 projectThat 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:
git switch main
git merge --squash fix-typo-in-readme
git commit -m "Improve the README (closes #12)"
git log --oneline --graphUpdating 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 READMETwo 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:
git switch main
git pull
git fetch --pruneUse a fresh branch for the next change rather than reusing the old one.
Common mistakes
- Opening a PR from
mainof your own copy. Use a topic branch somainstays 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
- In a practice repository with a local bare remote, create
docs-update, make two commits and push it. - Look at the change as a reviewer would, with
git diff main...docs-update. - Merge it into
mainwith--squashand commit. Compare the log to a--no-ffmerge made on a copy.
Show one possible answer
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 --graphThe log shows one new commit on main. With --no-ff you would see two commits plus a merge commit.
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.