Dependency & Upgrade Management
A dependency is code you didn't write but do ship; it needs the same update discipline as your own code, except split into lanes by risk: a security patch and a major-version upgrade are different kinds of change with different urgency, and treating them identically means either shipping security fixes too slowly or shipping breaking changes too casually.
Phase 1: Know what you ship (SBOM)
Before triaging any upgrade, the project needs an accurate inventory of its dependency tree, not just its direct package.json/requirements.txt/Cargo.toml entries; transitive dependencies carry just as much risk and are the ones people forget about.
- Generate a Software Bill of Materials (SBOM) in CycloneDX or SPDX format as part of the build, not as a one-off manual export; an SBOM that's stale by the next release doesn't answer "what are we actually running" when a new CVE drops.
- The SBOM is what a dependency-vulnerability scan (see
secure-coding's Phase 4) runs against; inventory and scanning are two steps of the same discipline, not separate concerns.
Phase 2: Two lanes, not one queue
Route every proposed upgrade (automated PR or manual bump) into the lane that matches its risk:
| Lane |
Trigger |
Review depth |
Cadence |
| Security fast-track |
a CVE against a version currently in use |
Doctrine's default policy is to automerge if it's a patch-level bump with a passing test suite and a short observation window; manual review only if it's also a major bump |
immediate, outside the batch schedule |
| Routine batch |
non-security patch/minor bumps |
grouped, reviewed together, low ceremony |
weekly or similar fixed cadence: batching avoids a constant trickle of one-line PRs eating review attention |
| Major-version migration |
a major version bump, even with no known CVE |
full review: read the changelog for breaking changes, run the full test suite, check every usage site the upgrade touches |
deliberate, scheduled, never auto-merged |
A security fix that also happens to be a major bump does not get the fast-track's automerge; the urgency of the CVE doesn't remove the risk of the breaking change; it goes to manual review, expedited.
Phase 3: Deprecating something others depend on
The same discipline a dependency owner owes you, you owe your own consumers (internal teams, API clients, plugin authors) when removing a capability:
- Signal the deprecation before removal, for an HTTP API, the
Deprecation and Sunset response headers (RFC 8594 / RFC 9745) plus a Link header pointing at migration docs; for a library, a deprecation warning at the call site plus a changelog entry.
- State a concrete removal date in the signal, not "in a future release"; an open-ended deprecation trains consumers to ignore the warning, since there's no deadline forcing action.
- Support the old and new path simultaneously during the window. Doctrine's default baseline is N-2: support the current version plus the two prior ones, so a consumer has a real runway rather than a single release cycle to migrate.
- Only remove the deprecated path after the stated sunset date has passed, removing it early because "surely nobody's still on it" breaks whoever didn't get the memo in time, which is exactly the failure this phase exists to prevent.
Phase 4: Safe major-version migration (as the consumer)
When upgrading a dependency across a major version, in order:
- Read the changelog for breaking changes, not just the version number's assumption of "probably fine."
- Check the codebase for every usage site the breaking changes actually touch; a global search for the API surface that changed, not a spot check.
- Apply the vendor's codemod/migration tool if one exists; hand-port only what it can't cover.
- Run the full test suite (leaning on
tdd's suite, not just the changed area) before merging.
- Where the ecosystem supports it, roll the upgrade out to a subset of traffic/environments first (the same progressive approach as
safe-deployment) rather than flipping every consumer to the new major version at once.
Done when
1---2name: dependency-upgrade-management3description: Discipline for keeping dependencies current and deprecating capabilities safely, an inventory (SBOM) of what's actually shipped, security patches on a fast lane separate from routine/major upgrades, and a stated deprecation window (Sunset/Deprecation headers, N-2 support) before removing anything consumers rely on. Use when upgrading a dependency, triaging a Dependabot/Renovate PR, deciding whether an upgrade is safe to automerge, or planning to deprecate or remove a capability others depend on.4---56# Dependency & Upgrade Management78A dependency is code you didn't write but do ship; it needs the same update discipline as your own code, except split into lanes by risk: a security patch and a major-version upgrade are different kinds of change with different urgency, and treating them identically means either shipping security fixes too slowly or shipping breaking changes too casually.910## Phase 1: Know what you ship (SBOM)1112Before triaging any upgrade, the project needs an accurate inventory of its dependency tree, not just its direct `package.json`/`requirements.txt`/`Cargo.toml` entries; transitive dependencies carry just as much risk and are the ones people forget about.1314- Generate a **Software Bill of Materials** (SBOM) in CycloneDX or SPDX format as part of the build, not as a one-off manual export; an SBOM that's stale by the next release doesn't answer "what are we actually running" when a new CVE drops.15- The SBOM is what a dependency-vulnerability scan (see `secure-coding`'s Phase 4) runs against; inventory and scanning are two steps of the same discipline, not separate concerns.1617## Phase 2: Two lanes, not one queue1819Route every proposed upgrade (automated PR or manual bump) into the lane that matches its risk:2021| Lane | Trigger | Review depth | Cadence |22|---|---|---|---|23| **Security fast-track** | a CVE against a version currently in use | Doctrine's default policy is to automerge if it's a patch-level bump with a passing test suite and a short observation window; manual review only if it's also a major bump | immediate, outside the batch schedule |24| **Routine batch** | non-security patch/minor bumps | grouped, reviewed together, low ceremony | weekly or similar fixed cadence: batching avoids a constant trickle of one-line PRs eating review attention |25| **Major-version migration** | a major version bump, even with no known CVE | full review: read the changelog for breaking changes, run the full test suite, check every usage site the upgrade touches | deliberate, scheduled, never auto-merged |2627A security fix that also happens to be a major bump does not get the fast-track's automerge; the urgency of the CVE doesn't remove the risk of the breaking change; it goes to manual review, expedited.2829## Phase 3: Deprecating something others depend on3031The same discipline a dependency owner owes you, you owe your own consumers (internal teams, API clients, plugin authors) when removing a capability:3233- Signal the deprecation before removal, for an HTTP API, the `Deprecation` and `Sunset` response headers (RFC 8594 / RFC 9745) plus a `Link` header pointing at migration docs; for a library, a deprecation warning at the call site plus a changelog entry.34- State a concrete removal date in the signal, not "in a future release"; an open-ended deprecation trains consumers to ignore the warning, since there's no deadline forcing action.35- Support the old and new path simultaneously during the window. Doctrine's default baseline is **N-2**: support the current version plus the two prior ones, so a consumer has a real runway rather than a single release cycle to migrate.36- Only remove the deprecated path after the stated sunset date has passed, removing it early because "surely nobody's still on it" breaks whoever didn't get the memo in time, which is exactly the failure this phase exists to prevent.3738## Phase 4: Safe major-version migration (as the consumer)3940When upgrading a dependency across a major version, in order:41421. Read the changelog for breaking changes, not just the version number's assumption of "probably fine."432. Check the codebase for every usage site the breaking changes actually touch; a global search for the API surface that changed, not a spot check.443. Apply the vendor's codemod/migration tool if one exists; hand-port only what it can't cover.454. Run the full test suite (leaning on `tdd`'s suite, not just the changed area) before merging.465. Where the ecosystem supports it, roll the upgrade out to a subset of traffic/environments first (the same progressive approach as `safe-deployment`) rather than flipping every consumer to the new major version at once.4748## Done when4950- [ ] The project's SBOM reflects the current dependency tree and is regenerated as part of the build.51- [ ] Every open upgrade PR is in the lane matching its actual risk, not queued generically.52- [ ] No capability was removed without a prior deprecation signal carrying a concrete removal date and a support window.53- [ ] A major-version upgrade was reviewed against its changelog and every real usage site, not merged on the strength of a passing CI run alone.54- [ ] Generated prose uses commas, colons, periods, or reworded sentences instead of em dashes.
aethrox