Merging
Merging
We use squash merges for all PRs. This means all your individual commits—including the "fix typo" and "oops forgot this" commits—get combined into a single, clean commit when merged to master.
Why Squash Merge?
Squash merging gives us several benefits:
Clean history - Master shows one commit per PR, not all the "fix typo" and "actually fix typo" commits
Easy to understand - Each commit represents a complete, coherent change
Simple to revert - Undo an entire feature with one revert instead of tracking down 47 commits
Good messages - You craft a polished commit message at merge time, not in the heat of development
Your branch keeps all the individual commits for reference. Master gets a clean, linear history that's easy to follow.
Squash Commit Message Format
When you squash merge, GitHub prompts you for a commit message. This is your chance to write a clean, polished message that explains what the PR accomplished:
<type>: <summary> (#PR-number)
* Key change 1
* Key change 2
* Key change 3
Superthread Card: [URL]
Here's a real example:
feat: add link archival endpoint (#42)
* Implement POST /api/v1/links/:id/archive endpoint
* Add database migration for archived_at column
* Include validation and tests
* Update API documentation
Superthread Card: https://app.superthread.com...
The bullet points summarize what changed. The Superthread card link connects the code to the project card.
Merge Checklist
One last check before clicking the merge button:
- All CI checks pass
- PR is marked "Ready for review" (not draft)
- Self-review is complete
- External reviews are approved
- All review feedback has been addressed
- Tests pass
- No linter errors
- Superthread card is linked
After Merging
Your code is now in master. A few housekeeping tasks:
- Delete the branch - GitHub offers a button right after merge. Click it. No need to keep the branch around once it's merged.
- Check Superthread - The card should update automatically to reflect the merge
- Pull master locally - Get the merged changes:
git checkout master && git pull
Sometimes things don't go smoothly. If you run into issues, check out the troubleshooting section.