1
# Dependency Upgrader — Workflow
2
3
Audits outdated dependencies, upgrades them in ascending risk order, runs the test
4
suite after each upgrade, and opens one PR per major (potentially breaking) version
5
bump — so a reviewer can accept or reject each risky upgrade independently, while
6
patch/minor bumps land together in a single low-risk PR.
7
8
Inputs: `package_manager` (auto-detected if omitted), `include_major` (default
9
`true`), `max_prs` (default `5`).
10
11
## Step 1 — Detect the package manager and list outdated deps
12
13
Detect from lockfile/manifest presence if not given explicitly: `package-lock.json` →
14
npm, `yarn.lock` → yarn, `pnpm-lock.yaml` → pnpm, `poetry.lock` → poetry,
15
`requirements.txt` → pip, `Cargo.lock` → cargo, `go.sum` → go modules.
16
17
Run the manager's outdated-listing command and capture, per dependency: current
18
version, latest version, and version type of the jump (patch/minor/major per semver).
19
20
| manager | outdated command |
21
|---|---|
22
| npm | `npm outdated --json` |
23
| yarn | `yarn outdated --json` |
24
| pnpm | `pnpm outdated --format json` |
25
| pip/poetry | `poetry show --outdated` (or `pip list --outdated`) |
26
| cargo | `cargo outdated --format json` (requires `cargo-outdated`) |
27
| go | `go list -u -m -json all` |
28
29
## Step 2 — Check for known vulnerabilities
30
31
Run the manager's audit command (`npm audit --json`, `pip-audit`, `cargo audit`, etc.)
32
if available. Any dependency with a known vulnerability gets upgraded regardless of
33
`include_major`/risk ordering — security fixes jump the queue and get their own PR
34
labeled accordingly, even if it's a major bump.
35
36
## Step 3 — Order by risk
37
38
1. **Patch bumps** (x.y.Z) — lowest risk, bundle all of these into a single PR.
39
2. **Minor bumps** (x.Y.z) — should be backward compatible per semver; bundle into a
40
   second PR, but read each package's release notes for the range being skipped and
41
   flag anything that mentions deprecations.
42
3. **Major bumps** (X.y.z) — one PR **per package**, since these can be breaking and
43
   need independent review/rollback. Skip this tier entirely if `include_major` is
44
   `false`.
45
4. **Security fixes** (from Step 2) — their own PR(s), opened first regardless of
46
   where they'd otherwise sort, clearly labeled as a security fix with the
47
   CVE/advisory reference.
48
49
Stop opening new PRs once `max_prs` is reached; report which upgrades were deferred
50
and why (not silently dropped).
51
52
## Step 4 — For each PR: upgrade, test, document
53
54
1. Create a branch: `build/upgrade-<package>-<new-version>` (or
55
   `build/upgrade-deps-patch` for the bundled patch/minor PRs), per
56
   `openagents/commit-conventions` naming if that package is present.
57
2. Apply the version bump via the package manager (not by hand-editing the lockfile).
58
3. Run the full test suite. If it fails:
59
   - First, check whether the failure is caused by the upgrade itself (read the
60
     failure, check the new package's changelog for a matching breaking change) vs.
61
     unrelated/flaky.
62
   - If caused by the upgrade and a straightforward fix is evident (e.g. a renamed
63
     import, an updated config key documented in the changelog), apply it and re-run.
64
   - If the fix isn't straightforward, do not force it — stop this specific upgrade,
65
     note the failure and likely cause in the PR/report, and move to the next
66
     dependency rather than shipping a red PR.
67
4. For major bumps: read the package's changelog/migration guide for the skipped
68
   version range and summarize relevant breaking changes in the PR description, even
69
   if tests pass — tests may not cover every affected code path.
70
5. Commit using the project's commit conventions if defined; otherwise
71
   `build(deps): bump <package> from <old> to <new>`.
72
6. Open the PR with a description covering: what changed, why (patch/minor/major/
73
   security), test result, and — for majors — the changelog summary and any manual
74
   verification still recommended before merge.
75
76
## Step 5 — Report
77
78
At the end of the run, summarize: PRs opened (with links), upgrades deferred (and
79
why — test failure, hit `max_prs`, needs `include_major`), and any dependency with a
80
known vulnerability that could *not* be upgraded (e.g. because a fix isn't released
81
yet) — flag these clearly since they need a different mitigation.
82
83
## Stop conditions
84
85
- No outdated dependencies found → report this and stop; don't open empty PRs.
86
- Package manager can't be detected and wasn't given explicitly → ask rather than
87
  guessing, since running the wrong manager's commands can corrupt the lockfile.
88
- A major upgrade's test failures point to a large, cascading breaking change (e.g. a
89
  framework's rewritten API) that would require substantial rework → stop that
90
  specific upgrade, document the scope of what changed, and let a human decide whether
91
  to invest in it, rather than attempting a large rewrite unprompted.
92