Fork only when you need a change upstream will not make soon, and only if someone will keep the fork patched. A fork gives control and removes the maintainer's future fixes unless you merge them. Try an update, an override, a contribution upstream or a replacement first.
What a fork really is
A fork is a copy you now maintain. The upstream project keeps publishing releases and security fixes. Your copy gets none of them unless you pull them in. For a client, that means a dependency that looks maintained but is not.
Decision guide
| Situation | Better first move |
|---|---|
| Bug with a fix merged upstream but not released | Wait for release, or pin a commit as a temporary step |
| Bug with a fix proposed upstream, not merged | Offer help; test the proposed patch |
| Vulnerability in a transitive package | Override to a fixed version |
| Maintainer unresponsive, project abandoned | Fork or replace |
| Feature the maintainers will not accept | Fork, if the feature is vital |
| One small local tweak | Patch at build time with a documented patch file |
If you do fork
- Fork under the client's organization, or agree where it lives and who owns it.
- Record why, what changed and the upstream commit you branched from.
- Keep the diff small. Large diffs make merging upstream changes painful.
- Publish under a clearly different package name or reference the repository directly, so nobody confuses it with the original.
- Set a review cadence to pull in upstream releases and advisories.
- Add the fork to the dependency inventory with a note that it is not the upstream package.
- Keep the license file and notices intact.
- Name an owner and an end date or exit plan.
The hidden costs
Security tools identify packages by name and version. A fork under a new name may not match any advisory, so scanners can go quiet while the code stays vulnerable. A fork under the old name on a private registry has the opposite risk, confusing resolution. Either way, you must watch upstream advisories by hand.
You also take on build, testing and release work that the original maintainer did for free.
Contributing back
If a change is generally useful, send it upstream. Upstream acceptance removes the maintenance burden. Even a rejected pull request leaves a public record that explains your patch to the next developer.
At handover
A fork is something the client inherits. Say so in the handover pack. Explain where it lives, what it changes, and who updates it. If you cannot commit to maintaining it, say that too, and recommend an exit.
Quick check
Is pinning a git commit the same as forking?
No. Pinning uses upstream code at a specific commit. You still depend on the upstream repository staying available, so track it.
Should the fork go on a public registry?
Usually keep it private or reference the repository. Publishing a fork publicly makes you a maintainer to everyone who installs it.
Last reviewed: 19 October 2026.
