Upstream Patches

上游补丁

upstream/

is a git submodule pointing to the upstream Terraform provider.

patches/

contains patch files applied on top of it. Use

./scripts/upstream.sh

to manage patch state.

upstream/

是指向上游Terraform provider的git子模块。

patches/

目录包含应用在该子模块之上的补丁文件。使用

./scripts/upstream.sh

管理补丁状态。

Default Behavior

默认行为

If fixing a regression introduced by an existing patch, amend the owning patch commit.
Do not create a new patch unless the user explicitly asks.

如果要修复现有补丁引入的回归问题，请修改对应所属补丁的提交。
除非用户明确要求，否则不要创建新补丁。

Commands Reference

命令参考

Command	Description
`./scripts/upstream.sh init`	Initialize upstream and apply patches to working directory
`./scripts/upstream.sh init -f`	Force re-initialize, discarding any changes
`./scripts/upstream.sh checkout`	Create branch with patches as commits for editing
`./scripts/upstream.sh rebase -i`	Interactively edit patch commits
`./scripts/upstream.sh rebase -o <commit>`	Rebase patches onto a new upstream commit
`./scripts/upstream.sh check_in`	Write commits back to patches and exit checkout mode

命令	描述
`./scripts/upstream.sh init`	初始化上游仓库并将补丁应用到工作目录
`./scripts/upstream.sh init -f`	强制重新初始化，丢弃所有变更
`./scripts/upstream.sh checkout`	创建包含补丁提交的分支以便编辑
`./scripts/upstream.sh rebase -i`	交互式编辑补丁提交
`./scripts/upstream.sh rebase -o <commit>`	将补丁变基到新的上游提交之上
`./scripts/upstream.sh check_in`	将提交写回补丁文件并退出检出模式

Guardrails

防护规则

Never commit directly to
```
upstream/
```
without
```
checkout/check_in
```
.
Direct edits under
```
upstream/
```
outside checkout are ephemeral during
```
upgrade-provider
```
; the tool resets submodule state.
Do not hand-edit
```
patches/*.patch
```
unless intentionally doing raw patch surgery.
Prefer non-interactive rewrite flow over interactive rebase for agents.

没有执行
```
checkout/check_in
```
操作时，永远不要直接提交到
```
upstream/
```
目录。
检出模式之外对
```
upstream/
```
下的直接编辑在
```
upgrade-provider
```
过程中是临时的；工具会重置子模块状态。
除非你故意要进行原始补丁修改操作，否则不要手动编辑
```
patches/*.patch
```
文件。
对于Agent来说，优先使用非交互式重写流程而非交互式变基。

Find Owning Patch First

先查找所属补丁

Before editing patch content, identify the owning patch/commit.

bash

./scripts/upstream.sh checkout

编辑补丁内容之前，先确定对应的所属补丁/提交。

bash

./scripts/upstream.sh checkout

Find candidate patch files by touched file path or unique hunk text

rg -n "path/to/file|unique_symbol" patches/*.patch

Optional: inspect candidate patch header/hunks

sed -n '1,120p' patches/00NN-Example.patch

Map patch file to commit in upstream checkout branch

patch=patches/00NN-Example.patch subject=$(sed -n 's/^Subject: [PATCH] //p' "$patch" | head -n1) cd upstream git log --oneline pulumi/patch-checkout --grep "$subject"

If needed, disambiguate by touched path

git log --oneline pulumi/patch-checkout -- path/to/file cd ..


Set `target_sha` to the owning commit and edit that commit, not `HEAD`.

git log --oneline pulumi/patch-checkout -- path/to/file cd ..


将`target_sha`设置为所属提交，编辑该提交而非`HEAD`。

Amend Existing Patch (Preferred, Non-Interactive)

修改现有补丁（推荐，非交互式）

bash

./scripts/upstream.sh checkout
cd upstream

target_sha=<owning-commit-sha>
base_sha=$(git rev-parse "${target_sha}^")
tmp_branch="rewrite-${target_sha:0:8}"

bash

./scripts/upstream.sh checkout
cd upstream

target_sha=<owning-commit-sha>
base_sha=$(git rev-parse "${target_sha}^")
tmp_branch="rewrite-${target_sha:0:8}"

Rebuild history from parent of target commit

git checkout -b "$tmp_branch" "$base_sha" git cherry-pick "$target_sha"

Apply fix and amend target commit

...edit files...

git add <files> git commit --amend --no-edit

Replay remaining commits

git cherry-pick "${target_sha}..pulumi/patch-checkout"

If cherry-pick conflicts occur:

resolve files

git add <resolved files>

git cherry-pick --continue

Move checkout branch to rewritten history

git branch -f pulumi/patch-checkout HEAD git checkout pulumi/patch-checkout git branch -D "$tmp_branch" cd ..


Interactive fallback:

```bash
./scripts/upstream.sh checkout
./scripts/upstream.sh rebase -i

git branch -f pulumi/patch-checkout HEAD git checkout pulumi/patch-checkout git branch -D "$tmp_branch" cd ..


交互式回退方案：

```bash
./scripts/upstream.sh checkout
./scripts/upstream.sh rebase -i

mark target commit as edit, amend, then continue

undefined

undefined

Remove Entire Patch

移除整个补丁

Use when a patch should be deleted completely.

bash

rm patches/00NN-Description.patch
./scripts/upstream.sh checkout
./scripts/upstream.sh check_in

当需要完全删除某个补丁时使用。

bash

rm patches/00NN-Description.patch
./scripts/upstream.sh checkout
./scripts/upstream.sh check_in

Remove Part of a Patch

移除补丁的部分内容

Use when only selected hunks/files should be removed from an existing patch.

Find owning patch/commit (
```
target_sha
```
) and use the amend workflow above.
Revert only unwanted changes from the target commit, then amend.

Example during amend step:

bash

cd upstream

当只需要从现有补丁中移除选定的补丁块/文件时使用。

查找所属补丁/提交（
```
target_sha
```
）并使用上述修改流程。
仅撤销目标提交中不需要的变更，然后修改提交。

修改步骤中的示例：

bash

cd upstream

Restore specific docs-only files from parent of amended commit

git checkout HEAD^ -- path/to/docs-only-file path/to/another-doc-file git add path/to/docs-only-file path/to/another-doc-file git commit --amend --no-edit cd ..

undefined

git checkout HEAD^ -- path/to/docs-only-file path/to/another-doc-file git add path/to/docs-only-file path/to/another-doc-file git commit --amend --no-edit cd ..

undefined

Create New Patch (Only If Requested)

创建新补丁（仅在被要求时执行）

bash

./scripts/upstream.sh checkout
cd upstream

bash

./scripts/upstream.sh checkout
cd upstream

...make changes...

git add <files> git commit -m "Describe new patch" cd .. ./scripts/upstream.sh check_in

undefined

git add <files> git commit -m "Describe new patch" cd .. ./scripts/upstream.sh check_in

undefined

Rebasing Patches to a New Upstream Version

将补丁变基到新的上游版本

bash

./scripts/upstream.sh checkout

bash

./scripts/upstream.sh checkout

Rebase onto the new upstream commit

./scripts/upstream.sh rebase -o <new_commit_sha>

Resolve any conflicts that arise

Write updated patch files

./scripts/upstream.sh check_in

undefined

./scripts/upstream.sh check_in

undefined

Verification Checklist

验证检查清单

Before

check_in

:

Confirm expected patch count change (
```
0
```
by default;
```
-1
```
for full patch removal).
Confirm whether target patch should remain present (default yes) or be removed (explicit deletion case).
Confirm you are editing the owning commit, not adding a new commit by accident.

After

check_in

:

Verify patch count matches expectation.
Verify target patch number/purpose is still present when expected.
Verify no unexpected new
```
00NN-*.patch
```
was introduced.

If checkout mode is stuck, use

./scripts/upstream.sh init -f

to reset.

执行

check_in

之前：

确认预期的补丁数量变化（默认是
```
0
```
；完全移除补丁的话是
```
-1
```
）。
确认目标补丁应该保留（默认是）还是被移除（显式删除场景）。
确认你正在编辑的是所属提交，而不是意外添加新提交。

执行

check_in

之后：

验证补丁数量符合预期。
验证预期保留的目标补丁编号/用途仍然存在。
验证没有意外引入新的
```
00NN-*.patch
```
文件。

如果检出模式卡住，使用

./scripts/upstream.sh init -f

重置。

upstream-patches

Original

Translation

Upstream Patches

上游补丁

Default Behavior

默认行为

Commands Reference

命令参考

Guardrails

防护规则

Find Owning Patch First

先查找所属补丁

Find candidate patch files by touched file path or unique hunk text

Find candidate patch files by touched file path or unique hunk text

Optional: inspect candidate patch header/hunks

Optional: inspect candidate patch header/hunks

Map patch file to commit in upstream checkout branch

Map patch file to commit in upstream checkout branch

If needed, disambiguate by touched path

If needed, disambiguate by touched path

Amend Existing Patch (Preferred, Non-Interactive)

修改现有补丁（推荐，非交互式）

Rebuild history from parent of target commit

Rebuild history from parent of target commit

Apply fix and amend target commit

Apply fix and amend target commit

...edit files...

...edit files...

Replay remaining commits

Replay remaining commits

If cherry-pick conflicts occur:

If cherry-pick conflicts occur:

resolve files

resolve files

git add <resolved files>

git add <resolved files>

git cherry-pick --continue

git cherry-pick --continue

Move checkout branch to rewritten history

Move checkout branch to rewritten history

mark target commit as edit, amend, then continue

mark target commit as edit, amend, then continue

Remove Entire Patch

移除整个补丁

Remove Part of a Patch

移除补丁的部分内容

Restore specific docs-only files from parent of amended commit

Restore specific docs-only files from parent of amended commit

Create New Patch (Only If Requested)

创建新补丁（仅在被要求时执行）

...make changes...

...make changes...

Rebasing Patches to a New Upstream Version

将补丁变基到新的上游版本

Rebase onto the new upstream commit

Rebase onto the new upstream commit

Resolve any conflicts that arise

Resolve any conflicts that arise

Write updated patch files

Write updated patch files

Verification Checklist

验证检查清单