Polished Pull Requests
Francisco, Martijn & TimS
October 2024
Polished Pull Requests
Francisco, Martijn & TimS
October 2024
Smooth code reviews
Do you want your PR to be reviewed quickly?
Do you want to stop putting the ticket number in every commit message?
Do you want to quickly understand what is being changed in the PR you are reviewing?
Author
Reviewer
Going back in time
Do you want to easily find the source of changes?
Do you want to understand what changed when and why?
Do you want to not be distracted by noise in the change history?
Historian
A two-pronged approach
Squash merges
Writing informative PRs
Available in GitHub
Use the Merge dropdown menu to select
Mechanics of regular merges (a.k.a. "explicit")
Time
Example: Merge pull request #6956 from lessonup/ED-1136/error-pages-editor
Mechanics of squash merges
Commit message = PR title + description
Time
Commits as snapshots
These commits are useful during development, but lose their function after work is merged.
Squash merges let us treat commits as true snapshots: no one will judge your commit messages. 🎉
We are removing the 1.0 constraint on commit messages. 🎉
What a squashed history looks like
When to use squash merges
Starting today:
Squash merges will be the default in GitHub (but you can override this)
Commit message checks are removed
✅ Normal development work
(recommended, but not required)
❌ Release branches
❌ Long-lived feature branches
⚠️ Stacking PRs (suggestion: git config --global merge.conflictstyle diff3)
Feel free to message #git-support if you need help
Questions?
Writing informative PRs
Provide context
clear title, helpful description
One self-contained change
easier to design well, easier to review, less likely to introduce bugs, easier to merge, easier to roll back
💡 Especially important with squash commits
Please read https://lessonup.atlassian.net/wiki/spaces/LD/pages/773455900/Code+Reviews
Providing context
Imagine your PR is read some time in the future,
by a colleague from a different team.
Title: short summary
Often the only thing visible in overviews.
Should stand alone and allow readers to skim through code history.
💡 The reader is unlikely to be aware of the context of your work.
Description: more details about what has changed
Add if relevant: how it was changed, why it was changed, related PRs/tickets/docs, screenshots, what to do to test the changes.
⚠️ Linking to a ticket alone is not enough.
Both of these might need updating after code review has completed
More details: https://lessonup.atlassian.net/wiki/spaces/LD/pages/773455900/Code+Reviews
GitHub flow right before merging
GitHub lets you update and confirm your squashed message before merging.
One self-contained change
Rename something and update all its uses
Refactor the Organizations module and add a new API method
Add Microsoft Ad tracking to analytics package and multiple frontend apps
Add existing analytics
to one frontend app
💡 Design the scopes of your PRs before writing them
Your responsibility as reviewer
Your job is to help the author write a good PR.
Feel free to take the time to review properly.
Try to review soon(tm), and help unblock the author.
Consider approving even if you ask for changes.
Push back if the PR is trying to do too much.
Reviewer
New workflow
We will experiment with the following setup and evaluate after a while.
Automated
Simplified PR template
Squash merges as default
No more mandatory JIRA tickets in commit messages
New Github Action to validate JIRA tickets in PR titles (already live)
Your workflow
Read the Confluence docs
Be vigilant as author and reviewer
Consider using squash merges when appropriate
Ask questions in #tech-only or #git-support