From 03f95ece09f7ec0654b1f0e0ba7361636d61f894 Mon Sep 17 00:00:00 2001 From: sparrowren <136441924+sparrowren@users.noreply.github.com> Date: Thu, 15 Oct 2026 10:21:08 +0800 Subject: [PATCH 1/2] docs: fix fork synchronization instructions --- README.md | 17 ++++++++++++----- README_zh.md | 17 ++++++++++++----- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 93605abb..a675f8fe 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,25 @@ If you have any comments or suggestions about the documentation, please submit t (1) Download the Asciidoc or Typora document editor. -(2) Check if the upstream repository has updates. If so, please sync to your own fork first: +(2) Before contributing, sync your fork with the upstream repository. In your local clone of your fork, check the configured remotes: +```sh +git remote -v ``` -git remote -git fetch upstream +If `upstream` is missing, add it once with `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`. -git merge upstream/main +Commit or stash any local changes before switching branches. The following example syncs the local `v5.6` branch; replace `v5.6` throughout with the branch you intend to contribute to: -git push +```sh +git fetch upstream +git switch v5.6 +git merge --ff-only upstream/v5.6 +git push origin v5.6 ``` +If the fast-forward merge fails because the branches have diverged, resolve the divergence before pushing. + (3) Familiarize yourself with the [Writing Guidelines](#writing-guidelines). ## Contribution Scope diff --git a/README_zh.md b/README_zh.md index 4301e8a9..f0a0f2f9 100644 --- a/README_zh.md +++ b/README_zh.md @@ -15,18 +15,25 @@ （1）下载Asciidoc或者Typora文档编辑器。 -（2）检查源仓库是否有更新，如果有更新请先更新并同步到自己的仓库。如有更新请参阅以下步骤，更新至最新版本： +（2）贡献前，请先将自己的 fork 与上游仓库同步。在自己 fork 的本地克隆目录中，检查已配置的远程仓库： +```sh +git remote -v ``` -git remote -git fetch upstream +如果尚未配置 `upstream`，请先执行一次 `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`。 -git merge upstream/main +切换分支前，请先提交本地修改，或使用 `git stash` 临时保存。以下示例同步本地的 `v5.6` 分支；如果要向其他分支贡献，请将所有 `v5.6` 替换为相应的分支名： -git push +```sh +git fetch upstream +git switch v5.6 +git merge --ff-only upstream/v5.6 +git push origin v5.6 ``` +如果分支历史已分叉，导致无法快进合并，请先处理分叉，再推送。 + （3）熟悉[文档写作规范](#规范说明) ## 贡献范围 From 56b343866cc017687cd2b1cfbbf08fdf10e33fa7 Mon Sep 17 00:00:00 2001 From: sparrowren <136441924+sparrowren@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:33:45 +0800 Subject: [PATCH 2/2] docs: clarify target branch selection and creation Use 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. --- README.md | 16 ++++++++++++---- README_zh.md | 16 ++++++++++++---- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a675f8fe..1613cd66 100644 --- a/README.md +++ b/README.md @@ -24,15 +24,23 @@ git remote -v If `upstream` is missing, add it once with `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`. -Commit or stash any local changes before switching branches. The following example syncs the local `v5.6` branch; replace `v5.6` throughout with the branch you intend to contribute to: +Commit or stash any local changes before switching branches. Choose the branch your PR will target, such as `master` or `v5.6`. Replace every `` below with the actual branch name: ```sh git fetch upstream -git switch v5.6 -git merge --ff-only upstream/v5.6 -git push origin v5.6 +git switch +git merge --ff-only upstream/ +git push origin ``` +If the target branch does not exist locally, replace the `git switch ` step above with the following command. This explicitly creates a local branch tracking your fork's branch, avoiding ambiguity when both remotes have a matching branch: + +```sh +git switch -c --track origin/ +``` + +Then continue with the merge and push steps above. + If the fast-forward merge fails because the branches have diverged, resolve the divergence before pushing. (3) Familiarize yourself with the [Writing Guidelines](#writing-guidelines). diff --git a/README_zh.md b/README_zh.md index f0a0f2f9..7e58958c 100644 --- a/README_zh.md +++ b/README_zh.md @@ -23,15 +23,23 @@ git remote -v 如果尚未配置 `upstream`，请先执行一次 `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`。 -切换分支前，请先提交本地修改，或使用 `git stash` 临时保存。以下示例同步本地的 `v5.6` 分支；如果要向其他分支贡献，请将所有 `v5.6` 替换为相应的分支名： +切换分支前，请先提交本地修改，或使用 `git stash` 临时保存。请选择 PR 要提交到的目标分支，例如 `master` 或 `v5.6`。将下文所有 `` 替换为实际分支名： ```sh git fetch upstream -git switch v5.6 -git merge --ff-only upstream/v5.6 -git push origin v5.6 +git switch +git merge --ff-only upstream/ +git push origin ``` +如果本地尚无目标分支，请将上述 `git switch ` 步骤替换为以下命令。它会明确创建本地分支并跟踪自己 fork 的对应分支，避免两个远程仓库都有同名分支时产生歧义： + +```sh +git switch -c --track origin/ +``` + +然后继续执行上述合并和推送步骤。 + 如果分支历史已分叉，导致无法快进合并，请先处理分叉，再推送。 （3）熟悉[文档写作规范](#规范说明)