-
Notifications
You must be signed in to change notification settings - Fork 7
Merge Strategy
The team uses a "Squash/Rebase and Merge Commit" Strategy for Pull Requests.
To summarize, you MUST first squash/rebase your local branch (to <= 5 commits) and push your local branch to origin (this may require force push and it is best to use --force-with-lease) and your branch MUST be "up to date" with main before you press the Merge button. Merge commit mode will keep all of your commits (max 5) and being up to date will ensure a linear history.
CI/CD will thus run on the "merged with main" result; and MUST pass before merge.
This will result in fewer, cleaner commits per PR, linear history, and non-breaking changes to main. Any escaped bugs should be easier to bisect search, find, fix and repair. Our limit of 5 commits is on the honor system.
It's your choice to rebase/squash your local branch BEFORE or AFTER you get a PR approval, but in general it's easier if you rebase AFTER approval. On the command line, this looks like git rebase -i HEAD~34 to rebase the last 34 commits interactively in an editor. Change the "pick" to "squash" for commits you want to smash into the previous pick. Edit your commit comments and finish. git push --force-with-lease origin my-cool-branch and you're good. This is on the honor system. It is best to use --force-with-lease otherwise (pure push --force) when multiple people are working on the same branch, one will force overwrite the others' work.
There is a new button on your PRs that allows you to update on top of main. This might be easy or hard depending on your changes. I prefer to git checkout main, git pull origin main, git checkout my-cool-branch, git rebase main and fix any conflicts. Once done I sometimes rebase interactively again to make it clean but often that is not needed. Then again git push origin my-cool-branch or maybe with --force if you had conflicts.
Once CI/CD runs on your updated branch, and passes, you are all set.
Checklist:
- your branch has at most 5 commits.
- you have a nice commit history that tells a story of this work
- your branch is up to date with main so it will just be a "fast forward" merge (i.e. you rebased on main)
- your CI/CD passes
Smash like and subscribe! (ha ha. Just press MERGE now)
┌──────────────────────────────────────────────────────────────────────────┐
│ Squash/Rebase + Merge-Commit PR Workflow (≤ 5 commits) │
└──────────────────────────────────────────────────────────────────────────┘
Developer machine (local) GitHub (origin) / CI / main
────────────────────────── ───────────────────────────
feature branch (many commits)
o--o--o--o--o--o--o--o--o 1) curate history (≤ 5 commits)
│ ┌───────────────────────────────────────┐
└───────────────▶ │ git rebase -i HEAD~N │
│ - squash/fixup to <= 5 commits │
│ - edit messages to "tell the story" │
└───────────────────────────────────────┘
│
│ 2) push branch (may need force)
▼
origin/my-cool-branch
o--o--o--o--o (≤ 5 commits)
│
│ 3) update to main (must be up to date)
▼
rebase onto latest main locally:
git checkout main && git pull origin main
git checkout my-cool-branch && git rebase main
│
│ (resolve conflicts if any)
│
▼
origin/my-cool-branch
M--M--M--M--M (rebased onto main)
│
│ 4) CI/CD runs on "merged with main" result
▼
┌──────────────────┐
│ CI/CD checks │
│ MUST PASS │
└──────────────────┘
│
│ 5) Merge (Merge Commit mode)
▼
main ──────────────────────────────o───────────────●
\
● Merge commit
\
o--o--o--o--o (your ≤ 5 commits)
Checklist before pressing MERGE:
[ ] branch has ≤ 5 commits (honor system)
[ ] commit messages tell a coherent story
[ ] branch is up to date with main (rebased on main; fast-forward possible)
[ ] CI/CD passes on the merged-with-main result