Field Guide (Software): A dependency change-window matrix for small product teams
Composer and npm updates are not all equal. Use this decision matrix before you merge: classify the change, pick the window, and document who signs off when a library touches payments, auth, or customer data.
Security scanners and Dependabot-style bots flood small teams with patch PRs every morning. Most are harmless. A few sit on the path between your login form and payroll export. This Field Guide is a decision matrix: classify the update, pick the window, and stop debating the same Composer diff in standup.
Pair it with this week's Swift Brief if leadership is asking about AI toolchain risk. The same matrix applies to SDK bumps that wrap model APIs.
What happened
Framework maintainers accelerated patch cadence after widely exploited library flaws.
Hosting panels flag outdated PHP extensions while your app still runs on a pinned
composer.lock from last quarter. Teams without a written rule either freeze
everything (and miss CVEs) or merge everything (and break checkout on a Friday).
Why you should care
- Revenue: A bad Stripe or tax-library update can block invoices until Monday.
- Risk: Unpatched auth or HTTP client libraries are the fastest path to breach headlines.
- Time: A one-page matrix saves hours of "is this safe?" threads per sprint.
Decision matrix (use before you merge)
For each proposed dependency change, answer the rows below. The window column is what you schedule on the calendar, not what you wish you had.
| Signal | Class | Window |
|---|---|---|
| CVE with public exploit; your version affected | P0 security | Same business day; staged prod after smoke tests |
| Touches auth, payments, PII serializers, or outbound webhooks | P1 critical path | Tue–Thu morning; paired reviewer; rollback tag ready |
| Minor/patch on dev-only or test tooling | P2 hygiene | Batch weekly; CI must stay green |
| Major semver on a core framework | P3 project | Dedicated change ticket; not mixed with feature work |
| No CVE; changelog is docs-only or typo fixes | P4 noise | Next monthly hygiene window or skip |
What to do this week
- Inventory (15 min). Export top 15 runtime packages from
composer.lockor lockfile. Highlight anything on the P0/P1 rows above. - Pick two patches (20 min). Merge at most one P0/P1 item and one P2 item. Anything else waits for the batch window.
- Smoke script (15 min). Document five clicks or API calls that must work post-deploy (login, one paid flow, one webhook, one report, one admin task).
- Log the decision (5 min). One line in your deploy log: package, class, window, reviewer. Future you will thank present you.
Myth vs field
Myth: "We should always stay on latest."
Field: Latest is a strategy for teams with continuous deploy and broad
test coverage. A clinic portal on shared hosting wins by predictable windows, not
by chasing every patch release the same hour it ships.
What we would build at Swift Media
On custom PHP and integration projects we wire this matrix into deploy checklists, optional staging snapshots, and monitoring on software delivery retainers. When an agent or automation proposes a bulk update, we require the P0–P4 label before merge.
This week
Paste the table into your internal wiki, run steps 1–4 once, and refuse Friday-afternoon P1 merges unless a CVE forces it. Next Field Guide pillar rotates to business.
Need a second opinion on lockfile risk before a big release? Talk with us.
Matt Potter · Swift Media