gh-dep-pr-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependency PR Triage

依赖PR分类处理

End-to-end workflow for triaging dependency update PRs: list them, assess merge safety, and fix CI failures — all with maximum parallelism. Do NOT merge PRs unless the user explicitly asks.

针对依赖更新PR的端到端处理流程：列出所有PR、评估合并安全性、修复CI失败——全程最大化并行处理。除非用户明确要求，否则请勿合并PR。

Phase 1: Discovery

第一阶段：发现

List all open dependency update PRs. Detect the bot automatically (Renovate, Dependabot, etc.).

bash

gh pr list --repo <owner/repo> --search "author:app/renovate OR author:app/dependabot" \
  --json number,title,author,mergeable,mergeStateStatus,statusCheckRollup,labels,updatedAt

Classify each PR into one of these buckets:

Bucket	Criteria	Next step
CLEAN	`mergeStateStatus=CLEAN` , all checks pass	Investigate for merge safety (Phase 2)
FAILING	One or more checks failing	Fix CI (Phase 3)
CONFLICTING	`mergeable=CONFLICTING` or `mergeStateStatus=DIRTY`	Resolve conflicts (Phase 3)

Present the full table to the user and ask how they'd like to proceed before moving to the next phase. Do not automatically start investigating or fixing.

列出所有处于打开状态的依赖更新PR，自动检测对应的机器人（Renovate、Dependabot等）。

bash

gh pr list --repo <owner/repo> --search "author:app/renovate OR author:app/dependabot" \
  --json number,title,author,mergeable,mergeStateStatus,statusCheckRollup,labels,updatedAt

将每个PR归入以下分类之一：

分类	判定标准	下一步
CLEAN（无问题）	`mergeStateStatus=CLEAN` ，所有检查均通过	评估合并安全性（进入第二阶段）
FAILING（检查失败）	存在一项或多项检查失败	修复CI（进入第三阶段）
CONFLICTING（存在冲突）	`mergeable=CONFLICTING` 或 `mergeStateStatus=DIRTY`	解决冲突（进入第三阶段）

向用户展示完整的分类表格，在进入下一阶段前询问用户的处理意愿，请勿自动开始调查或修复工作。

Phase 2: Investigate CLEAN PRs

第二阶段：调查CLEAN状态的PR

For each CLEAN PR, run investigations in parallel to assess merge safety:

Read the PR —

gh pr view <number> --json body,files,commits

Identify the dependency — what it does in this project, where it's used
Check the changelog — web search for release notes between old and new versions
Assess risk:
- Patch bump with no code changes → safe
- Minor bump with additive features only → safe
- Major bump or behavior changes → flag for user review
- Breaking changes documented → flag with details

Report back a structured summary per PR:

Dependency name and role in the project
Version change (from → to)
Breaking changes or behavior changes (if any)
Verdict: safe to merge or needs review with reasoning

After presenting the investigation summary, ask the user if they want to proceed with fixing failing PRs.

对每个CLEAN状态的PR并行执行调查，评估合并安全性：

查看PR详情 —

gh pr view <number> --json body,files,commits

识别依赖项 — 该依赖在项目中的作用、使用位置
查看变更日志 — 搜索新旧版本之间的发布说明
评估风险：
- 补丁版本更新且无代码变更 → 安全
- 小版本更新仅新增功能 → 安全
- 大版本更新或存在行为变更 → 标记需用户审核
- 文档中明确标注破坏性变更 → 标记并说明详情

按结构化格式返回每个PR的调查总结：

依赖名称及其在项目中的角色
版本变更（旧版本 → 新版本）
破坏性变更或行为变更（如有）
结论：可安全合并 或 需审核 并附上理由

展示调查总结后，询问用户是否要继续修复检查失败的PR。

Phase 3: Fix Failing PRs

第三阶段：修复检查失败的PR

Only proceed if the user confirms. For each failing PR, fix it in its own git worktree so fixes run in parallel without interfering with each other or the main working directory.

仅在用户确认后执行此步骤。对每个检查失败的PR，在独立的Git工作树中进行修复，确保修复工作并行执行且互不干扰，也不会影响主工作目录。

Common failure patterns

常见失败模式

Lint/format failures — Run the project's lint and format commands. Often the dependency update changes generated files or type signatures that need reformatting.
Lockfile conflicts — Accept main's lockfile version, then regenerate with the project's package manager.
Merge conflicts — Merge main into the PR branch, resolve conflicts, then verify all checks pass.

代码规范/格式检查失败 — 运行项目的代码规范和格式化命令。通常依赖更新会修改生成文件或类型签名，需要重新格式化。
锁文件冲突 — 采用主分支的锁文件版本，然后使用项目的包管理器重新生成锁文件。
合并冲突 — 将主分支合并到PR分支，解决冲突后验证所有检查均通过。

Fix workflow per PR

单个PR的修复流程

1. git worktree add <worktree-path> <pr-branch>
2. cd <worktree-path>
3. Merge origin/main if behind
4. Install dependencies
5. Run lint → fix issues
6. Run format → apply fixes
7. Run typecheck → fix type errors
8. Run doc/code generation if applicable
9. Verify all checks pass locally
10. Commit and push

Always run all project checks before pushing, not just the one that was failing — dependency updates can cause cascading issues.

1. git worktree add <worktree-path> <pr-branch>
2. cd <worktree-path>
3. 若落后于主分支，合并origin/main
4. 安装依赖
5. 运行代码规范检查 → 修复问题
6. 运行格式化命令 → 应用修复
7. 运行类型检查 → 修复类型错误
8. 如有需要，运行文档/代码生成命令
9. 本地验证所有检查均通过
10. 提交并推送

推送前务必运行全部项目检查，而非仅修复失败的那一项——依赖更新可能引发连锁问题。

Phase 4: Cleanup

第四阶段：清理

After all fixes are pushed and CI is passing, clean up local worktrees and branches created during the process.

bash

undefined

所有修复推送完成且CI检查通过后，清理过程中创建的本地工作树和分支。

bash

undefined

List worktrees to see what was created

列出所有工作树，查看已创建的内容

git worktree list

Remove each worktree

删除每个工作树

git worktree remove <worktree-path>

Or if directories were already deleted:

若目录已手动删除，执行以下命令清理：

git worktree prune

Only delete branches that were created by worktree agents during this session

仅删除本次会话中由工作树创建的分支

Track which branches you create and delete only those specific ones

记录创建的分支，仅删除这些特定分支

git branch -D <branch-1> <branch-2> ...


Always clean up before finishing — worktrees and local branches accumulate fast when fixing many PRs in parallel.

git branch -D <branch-1> <branch-2> ...


完成工作后务必清理——并行修复多个PR时，工作树和本地分支会快速累积。

Phase 5: Merge (only if user explicitly requests)

第五阶段：合并（仅在用户明确要求时执行）

Only proceed with merging if the user explicitly asks. Never auto-merge.

When merging multiple dependency PRs, each merge can create conflicts in remaining PRs (especially in lockfiles and generated files). Strategy:

Merge CLEAN PRs first — they're already verified and lowest risk
Merge in batches — after merging a batch, check remaining PRs for new conflicts
Re-resolve conflicts — for PRs that become DIRTY after earlier merges:
- Fix in a worktree: merge main, regenerate lockfile, push
- Wait for CI to pass
- Then merge

bash

gh pr review <number> --repo <owner/repo> --approve
gh pr merge <number> --repo <owner/repo> --squash

After each merge batch, verify remaining PRs' merge status before attempting the next batch. If a PR goes DIRTY, fix it (Phase 3 workflow) before merging.

仅在用户明确要求时执行合并操作，禁止自动合并。

合并多个依赖PR时，每次合并可能会导致剩余PR出现冲突（尤其是锁文件和生成文件）。策略如下：

优先合并CLEAN状态的PR — 这些PR已验证通过，风险最低
分批合并 — 合并一批PR后，检查剩余PR的合并状态
重新解决冲突 — 若合并后PR变为DIRTY状态，按第三阶段的流程修复后再合并：
- 在工作树中修复：合并主分支、重新生成锁文件、推送
- 等待CI检查通过
- 再执行合并

bash

gh pr review <number> --repo <owner/repo> --approve
gh pr merge <number> --repo <owner/repo> --squash

每批合并完成后，在尝试下一批合并前，务必验证剩余PR的合并状态。若某个PR变为DIRTY状态，先按第三阶段的流程修复再合并。

Key Principles

核心原则

Maximize parallelism — investigate and fix PRs concurrently using git worktrees
Verify locally before pushing — always run the full check suite, not just the failing check
Clean up after yourself — always remove worktrees and local branches when done
Report clearly — give the user a summary table at each phase so they can make informed decisions
Never merge without explicit request — the default workflow stops after CI is green; merging is a separate step only if asked

最大化并行处理 — 使用Git工作树并行调查和修复PR
推送前本地验证 — 务必运行完整的检查套件，而非仅修复失败的检查项
完成后清理环境 — 完成工作后务必删除工作树和本地分支
清晰汇报 — 在每个阶段向用户展示总结表格，以便用户做出明智决策
无明确请求不合并 — 默认流程在CI检查通过后结束；合并是仅在用户要求时才执行的独立步骤