A dependency override decision record should state what was overridden, why, who decided, which services are affected, what could break, and when it will be reviewed or removed. One page is enough. Its purpose is to let a stranger understand the decision a year later.
Why a record beats a code comment
An override usually lives in a manifest: an overrides block in package.json, a resolutions field in Yarn, a dependencyManagement section in Maven, or a constraint in Gradle. The syntax says what changed. It does not say why, who agreed, or when it can go away.
A comment next to the line helps, but disputes between teams need more. Several people need to see the same facts, and the record should survive a reorganization.
The template
Copy this into your repository, for example in a docs folder, one file per decision.
Title: Pin libfoo to 2.4.1 for all services
Date: 2026-10-19
Status: Accepted | Superseded | Expired
Decider: name and role
Raised by: name and team
Teams consulted: list
Context
- Package and versions involved
- Why a change was needed (advisory ID, bug, compatibility)
- Where it appears (services, depth in the tree)
Options considered
1. Upgrade the direct dependency that pulls it in
2. Override the transitive version at the root
3. Replace or fork
4. Accept the risk for a stated period
Decision
- What was chosen and the scope of the override
Consequences
- What may break, and the test evidence
- Who monitors it
Review date: yyyy-mm-dd
Removal condition: for example, when parent library reaches 5.0
Fill in each field with care
Scope. Say whether the override is global, or limited to the subtree of one package. npm documents that you can scope an override to a package when it appears as a child of another, and the same idea exists in other tools under different names.
Removal condition. This is the field most teams skip and later regret. Write the event that makes the override unnecessary, such as an upstream release that raises its own minimum.
Evidence. Link to the test run, the inventory showing affected services, and the advisory. Avoid pasting numbers you cannot reproduce.
Decider. Name the owner of the build where the override lives. Tools back this up: npm only considers overrides in the root project, and Cargo ignores patch settings defined in dependencies.
Keep the register current
A pile of records is not a register. Add a simple index file listing each record, its status and its review date, and check it on a fixed rhythm. Anything past its review date is either renewed with a new date and a reason, or removed.
Link each record from the manifest comment, so a developer who finds an unexplained override can reach the story in one click.
Quick check
Is this overkill for a small team?
Shrink it. Four lines will do: what, why, who agreed, review date. The point is that the reason is written somewhere other than someone's memory.
Where should records live?
In the repository that owns the manifest, or in a shared platform repository when the override affects a shared version list. Keep them next to the code so they are updated in the same pull request.
Sources
Last reviewed: 19 October 2026.
