Skip to content

Commit 56b3438

Browse files
committed
docs: clarify target branch selection and creation
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.
1 parent 03f95ec commit 56b3438

2 files changed

Lines changed: 24 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,23 @@ git remote -v
2424

2525
If `upstream` is missing, add it once with `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`.
2626

27-
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:
27+
Commit or stash any local changes before switching branches. Choose the branch your PR will target, such as `master` or `v5.6`. Replace every `<target-branch>` below with the actual branch name:
2828

2929
```sh
3030
git fetch upstream
31-
git switch v5.6
32-
git merge --ff-only upstream/v5.6
33-
git push origin v5.6
31+
git switch <target-branch>
32+
git merge --ff-only upstream/<target-branch>
33+
git push origin <target-branch>
3434
```
3535

36+
If the target branch does not exist locally, replace the `git switch <target-branch>` 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:
37+
38+
```sh
39+
git switch -c <target-branch> --track origin/<target-branch>
40+
```
41+
42+
Then continue with the merge and push steps above.
43+
3644
If the fast-forward merge fails because the branches have diverged, resolve the divergence before pushing.
3745

3846
(3) Familiarize yourself with the [Writing Guidelines](#writing-guidelines).

‎README_zh.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,23 @@ git remote -v
2323

2424
如果尚未配置 `upstream`,请先执行一次 `git remote add upstream https://github.com/IvorySQL/ivorysql_docs.git`。
2525

26-
切换分支前,请先提交本地修改,或使用 `git stash` 临时保存。以下示例同步本地的 `v5.6` 分支;如果要向其他分支贡献,请将所有 `v5.6` 替换为相应的分支名:
26+
切换分支前,请先提交本地修改,或使用 `git stash` 临时保存。请选择 PR 要提交到的目标分支,例如 `master` 或 `v5.6`。将下文所有 `<target-branch>` 替换为实际分支名:
2727

2828
```sh
2929
git fetch upstream
30-
git switch v5.6
31-
git merge --ff-only upstream/v5.6
32-
git push origin v5.6
30+
git switch <target-branch>
31+
git merge --ff-only upstream/<target-branch>
32+
git push origin <target-branch>
3333
```
3434

35+
如果本地尚无目标分支,请将上述 `git switch <target-branch>` 步骤替换为以下命令。它会明确创建本地分支并跟踪自己 fork 的对应分支,避免两个远程仓库都有同名分支时产生歧义:
36+
37+
```sh
38+
git switch -c <target-branch> --track origin/<target-branch>
39+
```
40+
41+
然后继续执行上述合并和推送步骤。
42+
3543
如果分支历史已分叉,导致无法快进合并,请先处理分叉,再推送。
3644

3745
(3)熟悉[文档写作规范](#规范说明)

0 commit comments

Comments
 (0)