Skip to content

docs: add upstream sync procedure - #31

Merged
dzannotti merged 1 commit into
masterfrom
docs/sync-procedure
Sep 15, 2026
Merged

dzannotti merged 1 commit into
masterfrom
docs/sync-procedure

Conversation

@dzannotti

Copy link
Copy Markdown

Why

GitHub's "N commits behind" counter is git rev-list --count HEAD..upstream/master — pure
graph reachability, unrelated to whether our files match upstream. Squash-merging an upstream
sync copies content without ancestry, so the counter sticks permanently and git merge-base
stops advancing, which makes every subsequent sync replay already-applied commits as conflicts.

We hit both halves of this on #28: the counter is stuck at 72, and the conflict resolution
silently dropped two upstream commits (recovered separately).

What

SYNC.md documents the preferred plain-merge flow, and — for when divergence forces a
reviewed PR instead — the mandatory audit for dropped commits plus the git merge -s ours
step that records ancestry without touching the tree.

Docs only, no code changes.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 15, 2026
@dzannotti
dzannotti merged commit 4bc01d0 into master Sep 15, 2026
3 checks passed
@dzannotti
dzannotti deleted the docs/sync-procedure branch September 15, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant