pulumi-upgrade-provider

Pulumi 提供程序升级

概述

运行 upgrade-provider --no-submit，修复已知故障，然后重新运行，直到成功。在运行循环中，工具会管理分支和生成的提交状态，但不会推送内容或修改 GitHub。成功后，先检查并修正本地结果，再按照工具打印的计划提交。

运行前检查

1. 记录现有更改，作为升级前基线：

baseline_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD")-baseline.txt"
git status --short --untracked-files=all | tee "$baseline_file"

现有更改不会阻止升级，但工具会广泛暂存文件，可能将这些更改纳入生成的提交。如果可行，请将明显无关的工作隔离到另一个分支或工作树中，移走仅限本地的文件，或者将未跟踪的本地文件添加到 .git/info/exclude。否则，请继续操作，并在最终审查时参考此基线。除非某个路径应对所有贡献者都忽略，否则不要添加仓库 .gitignore 规则。

2. 将运行日志保存在仓库之外，以免工具暂存该日志。

运行循环

1. 在仓库根目录运行：

log_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD").log"
upgrade-provider $ORG/$REPO --repo-path . --no-submit > "$log_file" 2> /dev/null

每次重试都要保留 --no-submit。

2. 等待运行完成（最多可能需要 10 分钟）。
3. 搜索日志中以 error: 开头的行，检查是否存在错误：

if command -v rg >/dev/null 2>&1; then
  rg -n '^error: ' "$log_file" || true
else
  grep -n '^error: ' "$log_file" || true
fi

4. 成功退出后，先检查工具是否判定无需升级：

if grep -Fq 'No actions needed' "$log_file"; then
  echo 'No actions needed'
fi

如果存在该提示，请报告提供程序已是最新版本，或请求的目标版本并非升级，然后成功停止。没有本地升级需要审查或提交。

5. 否则，从捕获的标准输出中提取并阅读完整的本地完成报告：

awk '/^Upgrade completed locally;/{found=1} found' "$log_file"

其中包括建议的 PR 正文和元数据、审查命令，以及所有跳过的提交操作。

6. 如果失败，请参照此技能目录中的 references/upgrade-provider-errors.md（而非仓库中的文件）进行修复，然后使用 --no-submit 重新运行。如果上游已从 Terraform Plugin SDKv2 迁移到 Plugin Framework，请按照该参考文件中的迁移指南指引操作，不要仅因框架变更就将其视为架构阻碍。对于涉及被忽略的 replace 指令或 unknown revision v0.0.0 的上游 go get 失败，在应用文档所述的 provider/go.mod 替换项后，使用 --target-version 重新运行；保留原有的主版本/非主版本意图，且只有在实际进行主版本升级时才添加 --major。
7. 如果修复需要创建、修改、移除或变基补丁，请使用 upstream-patches 技能处理补丁工作流程。中断的补丁工作流程必须先检查完整，再重新运行。
8. 如果你解决了冲突，请报告具体改动（文件路径 + 具体变更或保留的意图）。
9. 重复操作，直到工具打印 No actions needed 或本地完成报告和建议的 PR 计划。此次运行不得推送内容或修改 GitHub；之前的运行可能已创建分支或 PR。

何时停止并报告失败

符合以下任一条件时，停止重试并报告失败：

1. 找不到命令（退出代码 127）：upgrade-provider 工具不在 PATH 中。
2. 同一错误出现 3 次：尝试修复同一错误 3 次后仍未成功。
3. 未知错误模式：references/upgrade-provider-errors.md 中未涵盖该错误，且无法确定安全的修复方法。
4. 补丁状态不明确：无法确认所有补丁均已应用，且目标变基已完成。
5. 需要人工判断：修复需要用户输入，例如在多个有效实现方案中做选择，或对模块组织作出架构决策。上游破坏性变更、弃用或框架迁移本身不构成停止理由；只有升级实施存在尚未解决的选择时才停止。

停止时，请报告：

1. 遇到的错误。
2. 尝试过的修复（包括文件路径和变更）。
3. 需要人工介入的原因。
4. 已完成的部分工作。

审查本地升级

以工具的最终报告为准，确认基准分支、工作分支、拟定的 PR 标题／正文／元数据，以及跳过的提交操作。

1. 先审查有范围限制的摘要：

default_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
base_ref="origin/$default_branch"
git status --short --untracked-files=all
git log --oneline "$base_ref"..HEAD
git diff --shortstat "$base_ref"...HEAD
git diff --name-only "$base_ref"...HEAD | awk -F/ '{print $1}' | sort | uniq -c

提供程序升级可能会更改数千个生成的 SDK 文件。默认情况下，不要输出完整的分支差异。使用限制路径的 git diff "$base_ref"...HEAD -- <paths> 命令检查源代码、配置、补丁、架构和意外目录。对于生成的 SDK，除非确实需要完整差异，否则请检查摘要或特定文件。

将最终分支与升级前的基线进行交叉核对：

baseline_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD")-baseline.txt"
[ ! -f "$baseline_file" ] || cat "$baseline_file"

对于分支中包含的每个升级前已有路径，判断它是否应属于升级 PR。保留有意包含的路径；将无关工作移到其他分支／工作树，或在推送前从尚未发布的升级历史中移除。仅在同一分支上创建单独的提交只能隔离历史，无法将该路径从 PR 中移除；如果工具已提交，仅取消暂存也不够。即使重写了历史，也要撤销任何已泄露的凭据。

2. 发布前，必须审查生成文档替换项中是否存在未解决的占位符：

if [ -f provider/replacements.json ]; then
  if command -v rg >/dev/null 2>&1; then
    rg -n '"new":.*TODO|TODO' provider/replacements.json || true
  else
    grep -En '"new":.*TODO|TODO' provider/replacements.json || true
  fi
fi

如果在 provider/replacements.json 中发现任何 TODO：

• 将其视为提交前的阻断问题；替换值会渲染到生成的文档中。
• 检查每组 old／new 配对，并将 TODO 替换为具体的、面向 Pulumi 的措辞，通常使用 Pulumi、this provider 或 the provider。
• 如果仓库中有相应测试，请运行针对性验证：

cd provider && go test -v -run TestReplacementDoesNotIncludeTodos .

3. 如果升级更改了补丁，请审查已应用的提交，然后退出检出模式：

./scripts/upstream.sh checkout
git -C upstream log --oneline pulumi/checkout-base..pulumi/patch-checkout
# Inspect relevant commits with git -C upstream show <sha>.
./scripts/upstream.sh check_in

列出提交 SHA／标题，概述每个提交的意图，并指出行为变化或风险。审查后必须执行 check_in；如果让 upstream 留在 pulumi/patch-checkout，会阻止下一次安全的工具运行。

4. 对每项手动修复运行针对性验证，并补充针对性的后续提交。
5. 提交前，确保工作树干净。

提交已审查的升级

本地完成报告会列出拟定的 PR 元数据及所有跳过的操作。必须重现所有适用的操作，而不只是创建 PR：

1. 保留拟定的标题、正文、发布标签、审阅者和受理人。绝不要自行决定、推断或更改发布标签：提供程序升级遵循上游版本变更，因此标签表示该版本差异，而不是 Agent 对个别更改是否具有破坏性的判断。例如，上游从 v0.9.0 升级到 v0.10.0，即使包含具有破坏性行为变化，仍属于次要版本升级。使用 upgrade-provider 输出的确切标签；如有顾虑，向审阅者报告，但不要更改元数据。除非上游目标版本跨越当前上游主版本，否则绝不要添加 --major。
2. 如果修复解除了升级阻断，在可行的情况下，于提交前将以下部分追加到拟定正文中：

---

### Fixes applied to unblock upgrade

- <list concrete unblocker edits here, with file paths and intent>

3. 仅在审查后推送。工具会报告无条件强制推送；手动提交时，有意采用受租约保护的更安全方式，除非用户明确批准覆盖较新的远程工作：

branch=$(git branch --show-current)
git push --set-upstream origin "$branch" --force-with-lease

4. 使用 gh 按报告中的说明创建或更新 PR。
5. 如果有要求，将列出的升级问题分配给 PR 受理人。
6. 对于桥接升级，关闭列出的已被取代的桥接 PR，并评论替代 PR 的 URL。
7. 获取并报告最终 PR URL：

gh pr view --json url --jq .url || gh pr list --head "$(git branch --show-current)" --json url --jq '.[0].url'

如果提交前未包含修复部分，请在提交后追加，且不要替换现有正文：

repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
pr_number=$(gh pr view --json number --jq .number)
gh pr view --json body --jq .body > /tmp/pr_body.txt

cat <<'EOF' >> /tmp/pr_body.txt

---

### Fixes applied to unblock upgrade

- <list concrete unblocker edits here, with file paths and intent>
EOF

gh api -X PATCH "repos/$repo/pulls/$pr_number" --raw-field body="$(cat /tmp/pr_body.txt)"

使用 REST（gh api）而非 gh pr edit，以避免 GraphQL 项目卡片错误。保留现有正文；仅追加内容。

备注

• 较旧版本的 git 不支持 git rebase --continue --no-edit。请使用 git rebase --continue 并接受现有提交消息。
• 若要避免在 git rebase --continue 期间出现编辑器提示，请使用 GIT_EDITOR=true（或 GIT_EDITOR=:）运行。

防护措施

• 在 upgrade-provider 运行循环期间，切勿手动提交、推送或创建分支。
• --no-submit 成功后，可以提交针对性修正，并手动提交更改。
• 除非有意丢弃中断的补丁工作，否则切勿使用 ./scripts/upstream.sh init -f；此操作具有破坏性。
• 提交前，不要让 upstream 留在检出目录中，也不要让 Git 操作处于进行中状态。
• 不要暂存更改；请使用干净的工作树，或移除无关文件。

参考资料

• 有关中断的补丁状态、补丁冲突、从 SDKv2 迁移到 Plugin Framework、被忽略的 upstream 替换、vendored upstream 依赖项、.NET 重复文件以及新模块映射修复，请参阅此技能目录（而非仓库）中的 references/upgrade-provider-errors.md。