Write a one-page decision record in the pull request that adds the library: the problem, options considered, the evidence you checked, accepted risks, the exit trigger and a review date. It takes ten minutes and saves hours when someone asks, months later, why you chose it.
Why a record helps
Teams change. The person who picked a library leaves, an auditor asks about open source governance, or a new advisory forces a quick call about replacing it. Without a record, everyone reconstructs the reasoning from memory and guesses.
A record also forces the author to look at license and security signals before merging, which is when it is cheapest to change course.
The template
- Context. What problem does this solve, and for which service?
- Options. The libraries and the in-house alternative you considered.
- Decision. What you chose, at which version.
- Evidence. License, security policy, advisory check, maintenance, footprint. Link each.
- Risks accepted. What you know is imperfect.
- Mitigations. Wrapper, tests, pinning, monitoring.
- Exit trigger and plan. See how to write an exit plan.
- Owner and review date. Who watches it and when you will look again.
A filled example
| Field | Entry |
|---|---|
| Context | Need to parse uploaded spreadsheets in the import service |
| Options | Library A, Library B, writing a narrow parser |
| Decision | Library A at the current stable version, wrapped in an import module |
| Evidence | MIT license confirmed in file; SECURITY.md present; two past advisories, both fixed in releases; 6 transitive packages |
| Risks accepted | Single main maintainer; parser handles untrusted input |
| Mitigations | Input size limits, run parsing in a restricted worker, tests with malformed files |
| Exit trigger | Unfixed high severity advisory after 30 days, or archived repository |
| Owner and review | Import team lead, review in 90 days |
Names are generic on purpose; use your own.
Where to keep it
Keep the record close to the code, so it moves with the repository: the pull request description, a decisions folder in the repository, or an architecture note. Link it from the dependency file with a short comment if your team likes that. Avoid a wiki nobody opens.
Keep it short
A record that takes an hour to write will not get written. Aim for one screen. Skip sections that do not apply, and write "none" rather than leaving fields blank so readers know you considered them.
Use it later
- During the 90 day review, compare reality with the record.
- When answering customer questionnaires about open source use, the records show your process; see answering open source license questions in security questionnaires.
- When an advisory lands, the owner and exit trigger are already named.
Where Safeguard fits
Safeguard's compliance and evidence automation, with SBOM and dependency scanning, can help you keep an organized trail of what you ship. Try the free scan at gold.safeguard.sh/scan.
Quick check
Do we need a record for every package?
No. Use it for libraries that are hard to replace, handle untrusted input or sit on sensitive paths.
Should it be approved by someone?
The normal code reviewer approves it with the pull request. Escalate only if it trips an intake rule.
Last reviewed: 19 October 2026.
