Syncing with upstream

This guide brings upstream's latest game_rework into the fork and on into stable. Why the branches are laid out this way is on Branches and workflow.

Before you start

What you'll have

game_rework matching upstream exactly, and stable carrying upstream's new work alongside ours.

Turn on conflict memory

Do this once per clone:

git config rerere.enabled true

With it on, a conflict you resolve once is resolved the same way on every later merge.

Sync

Bring game_rework up to date

git fetch upstream
git switch game_rework
git merge --ff-only upstream/game_rework
git push origin game_rework

If the fast-forward fails, someone committed to game_rework. Nothing of ours belongs there: move the commit to its own branch, then reset game_rework to upstream/game_rework.

Merge it into stable

git switch stable
git merge game_rework
git push origin stable

Run this in the stable worktree if you use one.

Tip

Build and start the stack after the merge, and check it still comes up before you play on it.

Special cases

When upstream merges one of our pull requests

There's nothing extra to do. The change reaches stable through the same merge. An identical change merges cleanly. If the maintainer reworked it, take their version wherever the two conflict.

When a migration clashes

If upstream's new migrations clash with one of ours, reset the local database rather than repairing its migration history. A local test database holds nothing worth keeping. Running it locally has the reset.

Troubleshooting

Symptom	Cause	Fix
merge --ff-only refuses	game_rework has a commit upstream doesn't	Move it to its own branch and reset game_rework
The same conflict comes back on every merge	rerere is off	Turn it on, then resolve once more
Start-up fails after the merge with a migration error	Our migration and upstream's disagree on the history	Reset the database