An orphaned shared library should get one of three outcomes within a set time: a team adopts it, it is frozen with a published end date, or it is retired and consumers migrate. Leaving it as is means nobody patches its dependencies, and the risk grows quietly.
How to know a library is orphaned
Check four facts. The owner field points to a team that no longer exists. No commit or review in six months. No named person can publish a release. Consumers cannot say who to ask. Two of the four is enough to start the process.
The three paths
| Path | Choose it when | What it commits you to |
|---|---|---|
| Adopt | Many services depend on it and no good alternative exists | A team, a service level, a second maintainer |
| Freeze | A few consumers, stable behaviour, a replacement is planned | Security fixes only, a published end date |
| Retire | A maintained alternative exists or few consumers remain | A migration plan and a removal date |
Criteria to decide
- Consumer count. Use your dependency inventory, not memory. Count services and note which are internet facing.
- Sensitivity. A library that parses untrusted input or handles credentials deserves adoption or fast retirement, never a quiet freeze.
- Alternatives. Is there a maintained library, internal or external, that does the job? Compare on the features consumers actually use.
- Dependency health. Scan its own dependencies. If they carry open advisories, the library is already costing someone.
- Cost to adopt. Be honest about the hours. A team that adopts without time allocated is an orphan again in a year.
Time limits
Give the decision a deadline of thirty days from discovery. State it in the ticket. Without a deadline the review itself gets orphaned.
For a freeze, publish the end date to every consumer and mark the package deprecated. npm documents that its deprecate command adds a warning shown to everyone who tries to install the package, and it works on version ranges. Other registries have their own mechanisms, so check yours.
Retirement steps
- Announce the end date and the replacement.
- Open migration tickets in each consuming team's queue.
- Track consumers weekly until the count reaches zero.
- Deprecate, then archive the repository, then remove access.
Related reading: one person maintains our shared library.
Safeguard can help with the inventory side: its SBOM and dependency scanning shows which services pull in a given internal library, and you can run a free scan at gold.safeguard.sh/scan.
Quick check
Is freezing a library safe?
Only if security fixes still ship. A freeze that stops all work leaves known vulnerabilities in place, so it needs an end date and a named person who can publish a fix.
Who decides between adopt and retire?
The engineering manager or architect group that owns the platform area, with input from the largest consumers. Record the decision and the date.
Sources
Last reviewed: 19 October 2026.
