Introduction
On GitHub, changes rarely go straight into main. Instead, a developer pushes a branch and opens a pull request: a page that shows the diff, runs automated tests, and lets teammates comment, suggest changes and approve. Pull requests are where most teams discuss code. When commit messages follow a shared format, the same history can also generate release notes and version numbers automatically.
How it works
The pull request workflow:
- create a branch and commit your change;
- push the branch (
git push -u origin feature), or, for a project you cannot push to, push to your fork (your own copy on GitHub); - open a pull request from your branch into
main; - automated checks run, and reviewers comment and approve; you push more commits to address feedback;
- a maintainer merges it, and the branch is deleted.
GitHub offers three merge methods: a merge commit (keeps every commit and records the merge), squash and merge (combines the whole PR into one commit on main), and rebase and merge (replays the commits onto main without a merge commit).
Conventional Commits give commit subjects a structure:
type(scope)!: description
- type:
feat(a new feature),fix(a bug fix), or others such asdocs,refactor,perf,test,build,ci,chore,style,revert; - scope (optional): the part of the project, in brackets:
feat(search): …; - ! (optional): marks a breaking change;
- a colon, a space and a short description.
Release tools read these messages. Since the last release: any breaking change bumps the major version (and resets minor and patch), otherwise any feat bumps the minor version (and resets patch), otherwise any fix or perf bumps the patch. If none of these appear, no release is needed. The same information groups the changelog into sections.
gh pr create --fill # open a PR with the GitHub CLI
gh pr checkout 42 # try someone's PR locally
git commit -m "fix(login): accept emails with a plus sign"
Example
import re
PATTERN = re.compile(r"^(\w+)(?:\(([a-z0-9-]+)\))?(!)?: (.+)$")
commits = [
"feat(search): add filters",
"fix: handle empty query",
"docs: explain the API",
"feat(api)!: remove the v1 endpoint",
"update stuff",
]
sections = {"breaking": [], "feat": [], "fix": []}
for subject in commits:
m = PATTERN.match(subject)
if not m:
print(f"not a conventional commit: {subject!r}")
continue
kind, scope, bang, description = m.groups()
entry = description + (f" ({scope})" if scope else "")
if bang:
sections["breaking"].append(entry)
if kind in sections:
sections[kind].append(entry)
major, minor, patch = 1, 4, 2
if sections["breaking"]:
major, minor, patch = major + 1, 0, 0
elif sections["feat"]:
minor, patch = minor + 1, 0
elif sections["fix"]:
patch += 1
print(f"## v{major}.{minor}.{patch}")
for key, title in [("breaking", "BREAKING CHANGES"), ("feat", "Features"), ("fix", "Bug Fixes")]:
if sections[key]:
print(f"### {title}")
for entry in sections[key]:
print(f"- {entry}")Line by line
- A regular expression reads the type, optional scope, optional
!and description of each subject. - Commits that do not match the format are reported and skipped.
- Entries are collected into breaking changes, features and fixes;
docscommits do not appear in the changelog. - Because one commit is breaking, version 1.4.2 becomes 2.0.0.
- The changelog lists breaking changes first, then features, then fixes, each with its scope.
Expected result
not a conventional commit: 'update stuff'
## v2.0.0
### BREAKING CHANGES
- remove the v1 endpoint (api)
### Features
- add filters (search)
- remove the v1 endpoint (api)
### Bug Fixes
- handle empty query
In the real world
Tools such as semantic-release and release-please create version tags, GitHub releases and changelogs from conventional commits, and commitlint rejects messages that do not follow the format. Squash merging often turns the pull request's title into the single commit message, so teams check that titles follow the convention. Code owners files make the right reviewers review each part of a repository.
Common mistakes
- Opening huge pull requests that are hard to review; split them.
- Forgetting the ! or BREAKING CHANGE on an incompatible change, so users get it in a minor release.
- Pushing fixes for review comments to main instead of to the PR branch.
- Mixing a feature and an unrelated fix in one commit, so it cannot be described by one type.
Best practices
- Keep pull requests small and focused, with a description of what and why.
- Review others' code kindly and specifically; suggest, explain, and approve when it is ready.
- Use conventional commits so that releases and changelogs can be automated.
Summary
A pull request proposes merging a branch, with review and automated checks before merging by commit, squash or rebase. Conventional Commits structure messages as type(scope)!: description, letting tools compute the next semantic version (breaking → major, feat → minor, fix → patch) and write the changelog.
Quick check
Key takeaways
- A pull request turns a branch into a reviewable proposal; nothing reaches main without review and passing checks.
- Conventional commit types such as feat and fix tell tools what kind of change each commit is.
- A breaking change raises the major version, a feature the minor, and a fix the patch.
Practice problems for this lesson
My notes
Write down what you want to remember from this lesson. Notes are saved on this device as you type, and appear on your dashboard.