upstream-patches

上游补丁

upstream/ 是指向上游 Terraform 提供程序的 git 子模块。patches/ 包含应用在其上的补丁文件。使用 ./scripts/upstream.sh 管理补丁状态。

默认行为

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

命令参考

命令	说明
./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	将提交写回补丁并退出检出模式

注意事项

• 未执行 checkout/check_in 时，绝不要直接提交到 upstream/。
• 在检出模式之外直接编辑 upstream/ 下的内容，在执行 upgrade-provider 时只是临时的；该工具会重置子模块状态。
• 不要手动编辑 patches/*.patch，除非你有意直接修改补丁内容。
• 对于 Agent，优先使用非交互式重写流程，而不是交互式变基。

首先查找所属补丁

编辑补丁内容之前，先确定其所属补丁／提交。

./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 ..

如果无法使用 rg，请使用 grep -En 搜索补丁。将 target_sha 设置为所属提交，并编辑该提交，而不是 HEAD。

修改现有补丁（首选，非交互式）

./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 ..

交互式备用方案：

./scripts/upstream.sh checkout
./scripts/upstream.sh rebase -i
# mark target commit as edit, amend, then continue

删除整个补丁

当需要彻底删除补丁时使用。

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

删除补丁的一部分

当只需从现有补丁中删除选定的代码块／文件时使用。

1. 查找所属补丁／提交（target_sha），并使用上述修改工作流。
2. 仅还原目标提交中不需要的更改，然后修改提交。

修改提交步骤中的示例：

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 ..

创建新补丁（仅在用户要求时）

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

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

./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

验证清单

执行 check_in 之前：

• 确认补丁数量变化符合预期（默认 0；彻底删除补丁时为 -1）。
• 确认目标补丁应保留（默认是）还是应删除（明确要求删除的情况）。
• 确认你正在编辑所属提交，而不是意外添加新提交。

执行 check_in 之后：

• 确认补丁数量符合预期。
• 在预期应保留的情况下，确认目标补丁的编号／用途仍然存在。
• 确认没有意外引入新的 00NN-*.patch。

中断的检出或变基

默认保留工作。检查 git -C upstream status，完成当前正在进行的 git am／变基，验证每个补丁均已应用，然后再运行自动化之前执行 ./scripts/upstream.sh check_in。检出过程中断时，会针对每个补丁分别调用 git am，因此可能尚未处理后续补丁文件。

仅当你有意丢弃所有中断的工作时，才使用 ./scripts/upstream.sh init -f。它可能会删除冲突解决结果、补丁提交、操作元数据和未跟踪文件；这不是解决检出卡住问题的常规恢复方式。