相依性升級規劃工具
產出一個計劃。在使用者批准計劃之前,不要升級任何項目。
程序
- 從 manifest 檔案偵測生態系統:
package.json、requirements.txt或pyproject.toml、go.mod、Cargo.toml、Gemfile、pom.xml。如果有多個 manifest,詢問使用者要規劃哪一個,或者分別規劃。 - 從 manifest 和 lockfile(
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如果該工具不可用,請說明,並直接從 manifest 處理,將版本標記為未驗證。
- npm:
- 將每個過時套件分類:
- 修補 / 次要 — 通常是安全的。
- 主要 — 在規劃前,先閱讀 changelog 或 release notes 以了解重大變更。
- 安全性 — 任何被
npm audit、pip-audit、govulncheck、cargo audit或bundle audit標記的項目。這些優先處理。
- 將工作排序成批次:
- 批次 0:安全性修復,即使涉及主要版本。
- 批次 1:修補和次要版本升級,按區域分組。
- 批次 2:沒有跨相依性的主要版本,每個版本一個提交。
- 批次 3:必須一起升級的主要版本(例如框架及其外掛)。
- 對於每個批次,說明:套件名稱、從/到版本、適用的重大變更、必須修改的程式碼或設定,以及如何驗證。
輸出範本
## 升級計劃
生態系統:<npm / pip / go / cargo / ...>
Manifest:<路徑>
### 批次 0 — 安全性
| 套件 | 從 | 到 | 原因 | 重大變更? |
| --- | --- | --- | --- | --- |
### 批次 1 — 修補和次要
...
### 批次 2 — 主要,獨立
...
### 批次 3 — 主要,必須一起移動
...
### 驗證
每個批次之後:<證明沒有回歸的確切指令>
### 復原
每個批次:<如何還原,例如使用批次提交的 git revert>
### 延遲
<刻意保留不處理的套件,以及原因>
規則
- 規劃期間不得編輯 manifest。產出計劃後即停止。
- 當有可用的主要版本升級時,務必閱讀實際的 changelog;不要因為主要版本號碼變更就假設是重大變更。
- 務必指定驗證指令。「執行測試」不是一個指令;
npm test才是。 - 當你決定不處理某個套件時,務必說明延遲原因——例如,無法讀取某個主要版本的 release notes。
- 不得執行會修改樹狀結構的 install、upgrade 或 audit 指令。
npm outdated、npm audit及其對應指令是唯讀的,因此可以使用。
支援檔案
references/upgrade-strategy.md 說明批次處理、semver 邊界情況,以及如何處理必須保留的套件。