Skip to content

docs: fix fork synchronization instructions - #338

Merged
gaoxueyu merged 2 commits into
IvorySQL:v5.6from
sparrowren:docs/fix-contribution-sync
Oct 21, 2026
Merged

gaoxueyu merged 2 commits into
IvorySQL:v5.6from
sparrowren:docs/fix-contribution-sync

Conversation

@sparrowren

@sparrowren sparrowren commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Both contribution READMEs tell contributors to merge upstream/main, but this repository has no main branch. A fresh clone of a contributor's fork also does not have an upstream remote configured.

Update both READMEs to explain the one-time upstream setup and selecting the branch the PR will target. Use <target-branch> throughout, with instructions to replace it with a real branch name such as master or v5.6. If the branch does not exist locally, explicitly create it tracking origin/<target-branch> so Git does not have to choose between matching branches on both remotes. Synchronize with upstream/<target-branch> using a fast-forward merge, then push to the fork. Explain saving local changes and resolving divergent histories before pushing.

Validation:

  • Reproduced the original missing-upstream and missing-main errors.
  • Ran the command blocks from both READMEs against local bare upstream/fork repositories: eight scenarios covering both languages, master and v5.6, and existing and missing local target branches. Each local branch and fork reached the incoming upstream commit.
  • Reproduced the ambiguous git switch error when the local target branch is absent and both remotes contain it; verified the explicit creation command tracks origin/<target-branch>.
  • Confirmed that --ff-only rejects divergent histories and preserves both the local commit and the fork in all eight scenarios.
  • git diff --check passed.

Initial error reproduction ran with Git for Windows. The expanded target-branch validation ran in WSL Ubuntu with Git 2.43.0. All validation pushes targeted local fixture repositories.

@github-actions
github-actions Bot temporarily deployed to pull request October 15, 2026 02:27 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@sparrowren
sparrowren marked this pull request as ready for review October 15, 2026 02:28
@jiaoshuntian

Copy link
Copy Markdown
Contributor

Thanks for fixing the synchronization instructions and updating both READMEs.

Could we use <target-branch> instead of hardcoding v5.6? Both master and v5.6 are maintained, so the instructions should explain that contributors need to select the branch their PR will target:

git fetch upstream
git switch <target-branch>
git merge --ff-only upstream/<target-branch>
git push origin <target-branch>

Please clarify that <target-branch> must be replaced with the actual branch name, such as master or v5.6.

Also, if the target branch does not exist locally, git switch <target-branch> can fail because both remotes contain a matching branch. Please document explicitly creating it with git switch -c <target-branch> --track origin/<target-branch> in that case, and keep both language versions aligned.

Use <target-branch> in both synchronization guides and explain that it
must be replaced with the PR's actual target, such as master or v5.6.
Document explicitly creating a missing local branch tracking origin to
avoid ambiguous remote branch guessing. Keep both READMEs aligned.

Validate both branch names with existing and missing local branches in
both languages, including divergence rejection, using local fixtures.
@github-actions
github-actions Bot temporarily deployed to pull request October 19, 2026 08:37 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@gaoxueyu
gaoxueyu merged commit 43fb9d7 into IvorySQL:v5.6 Oct 21, 2026
2 checks passed

This branch was previously deployed

1 inactive deployment
pull request — 56b34386 Deployed Oct 19, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants