A good override request fits on half a screen: what package, which versions, why, which services, how it was tested, who owns it, and when it expires. Reviewers approve complete requests quickly and bounce incomplete ones. Put the template in your pull request form so it is the default.
The template
Copy this into a pull request template file.
Override request
Package and range being replaced:
Forced version:
Reason (advisory id, bug link, or fixed release):
Which dependency pulls it in (output of the tree command):
Services or workspaces that resolve it:
Scope used (global, under a parent, or version specific):
Tests run and results:
Owner:
Review date to retry removal:
Alternative considered (upgrade parent, exclusion, replacement):
Why each field exists
Package and forced version. The reviewer needs the exact change, not a description.
Reason. Without an identifier, nobody can later judge whether the override is still needed.
Which dependency pulls it in. Overrides exist to fix packages you do not control directly. Knowing the parent shows whether upgrading the parent is possible instead.
Services that resolve it. This lists who is affected, and who to tag for review.
Scope. In npm, the documentation describes a global form, a form scoped under a parent, and a form that matches a specific parent version. The narrowest scope that works is safest. In Yarn the resolutions field offers one level of specificity for a parent.
Tests. Show results from each affected service, not a general statement.
Owner and review date. An override without these becomes permanent by neglect.
Alternatives. Forcing a version is one of several fixes. Others include upgrading the parent, excluding an unused component, or replacing the parent.
When reviewers should say no
- The forced version is a different major version and no tests cover the affected paths.
- The override targets a direct dependency and conflicts with its declared range. npm reports an error in that case unless the specs match.
- The package is not shipped, and a routine update would do.
- The scope is wider than the problem.
- There is no owner.
How to make it stick
Add a CI check that fails when the override block changes without the template fields in the PR description. Keep an index of active overrides in one file or table so the quarterly review is a short read, not a code search.
A filled in example
Package and range being replaced: a parsing library, any 2.x version below the fixed one. Forced version: the fixed patch release. Reason: advisory identifier plus a link. Pulled in by: the web framework's upload module. Services: checkout and reporting. Scope: under the web framework only. Tests: both service suites green, plus one new test that parses a sample file. Owner: the checkout team. Review date: first week of next quarter. Alternative considered: upgrading the web framework, which needs a major version change and is scheduled separately.
Notice that the example is short. Nothing in it needs a meeting.
Small teams, small version
If your team is three people, shrink the template to four lines: package and version, reason, tests, review date. The goal is a durable explanation, not paperwork.
Quick check
Do we need a template for every override?
Use it wherever the override changes a version that ships. A short version works for small teams.
What is the most important field?
The reason with an identifier. It tells the next person whether the override is still needed.
Sources
Last reviewed: 19 October 2026.
