依赖升级规划器 是做什么的?
制定一个计划。在用户批准计划之前,不要升级任何内容。
流程
- 从清单文件中检测生态系统:
package.json、requirements.txt或pyproject.toml、go.mod、Cargo.toml、Gemfile、pom.xml。如果存在多个,询问要规划哪一个,或分别规划它们。 - 从清单文件和锁文件(
package-lock.json、poetry.lock、go.sum、Cargo.lock、Gemfile.lock)读取当前版本。 - 使用生态系统自身的工具查找可用版本,并报告你实际获得的输出:
- npm:
npm outdated - Python:
pip list --outdated或uv pip list --outdated - Go:
go list -u -m all - Rust:
cargo outdated - Ruby:
bundle outdated如果工具不可用,请说明情况并从清单文件入手,将版本标记为未验证。
- npm:
- 对每个过时的包进行分类:
- 补丁/次要 —— 通常安全。
- 主版本 —— 在规划之前,阅读变更日志或发布说明以了解破坏性变更。
- 安全 ——
npm audit、pip-audit、govulncheck、cargo audit或bundle audit标记的任何内容。这些优先处理。
- 将工作分批排序:
- 批次 0:安全修复,即使是主版本。
- 批次 1:补丁和次要升级,按区域分组。
- 批次 2:没有交叉依赖的主版本,每次提交一个。
- 批次 3:必须一起移动的主版本(例如框架及其插件)。
- 对于每个批次,说明:包含的包、从/到版本、适用的破坏性变更、必须修改的代码或配置,以及如何验证。
输出模板
## 升级计划
生态系统:<npm / pip / go / cargo / ...>
清单文件:<路径>
### 批次 0 — 安全
| 包 | 从版本 | 到版本 | 原因 | 是否破坏性? |
| --- | --- | --- | --- | --- |
### 批次 1 — 补丁和次要
...
### 批次 2 — 主版本,独立
...
### 批次 3 — 主版本,必须一起移动
...
### 验证
每个批次之后:<证明没有回归的确切命令>
### 回滚
每个批次:<如何恢复,例如通过 git revert 该批次的提交>
### 推迟
<有意保留不动的包及其原因>
规则
- 在规划期间切勿编辑清单文件。输出计划,然后停止。
- 在有可用变更日志时,阅读主版本升级的实际变更日志;不要因为主版本号改变就假定是破坏性变更。
- 始终指明验证命令。“运行测试”不是一个命令;
npm test才是。 - 当你决定推迟一个包时,明确说明原因 —— 例如,某个主版本的发布说明无法阅读。
- 不要运行会修改树结构的安装、升级或审计命令。
npm outdated、npm audit及其等效命令是只读的,可以正常使用。
支持文件
references/upgrade-strategy.md 解释了分批策略、语义化版本边界情况以及如何处理必须保留不动的包。