Six questions to ask before you adopt that open-source component

You are standing in front of a component you need. An identity provider, a Postgres operator, a GitOps engine, a build pipeline. You have to decide whether to wrap it — adopt the finished open-source piece and put a thin shell of your own code around it — or to build it yourself. Both paths have a price. Both have a payoff. What you need is not a three-hundred-page architecture textbook, but a method you can apply this afternoon.

Over the past few years I've migrated several mid-market platforms back off the hyperscaler default onto independent stack choices, and in the process I've made each of these decisions a few times. Six axes have crystallised out of that practice. Together they translate the wrap-or-build question into an honest ADR — not political justification, but a defensible architecture decision.

Six axes. One question per axis. In this order — which is not academic but empirical: from the most common killer to the most cynical detail.

1. Maturity — is the component architecturally stable?

Maturity is not the same as age. A twelve-year-old component whose last architectural overhaul happened six months ago is not mature in the sense that matters here. Maturity assumes a stable architecture that has not moved fundamentally in at least the past two years.

Three signals I check:

• A stable major version (1.0+) for at least 24 months.
• More than three independent production adoptions, ideally publicly verifiable (case studies, conference talks).
• A consistent documentation line — not three generations of docs, two of which are stale.

If you wrap an immature component, you wrap something that is still going to change fundamentally. Every major architectural shift forces a rewrite of your companion layer. Do that two or three times and you've actually built it yourself — only in the costume of wrapping.

2. Maintainership — who looks after it, and for how long?

Maintainership decides whether the component will still exist in five years, whether it will pull a license shift, and whether a maintainer burning out will bring the project to a halt. Three structural patterns show up in the market:

• Foundation-anchored (CNCF, Apache, Eclipse, OpenJS): distributed governance, CLA discipline, formal maturity levels. This is the structural insurance against sudden license changes and abrupt maintainership breaks.
• Single-sponsor with a clear strategy (Sidero Labs behind Talos, Zitadel AG behind Zitadel): honest, workable, but needs a plan B in the ADR.
• Single maintainer — one person, no backup. No wrapping choice without an explicit fork plan.

The diagnostic tool: look at the list of independent top-contributors over the last twelve months. If 95% of substantive commits come from a single company, your bus factor is effectively the company, not the person — and a company can change strategy overnight.

3. Licence — and what happens if it changes?

Licence either gets ignored (»Apache 2.0, fine«) or made into the first question. Both are wrong. A mature component with clear maintainership survives a license crisis; an immature one with shaky maintainership does not. That's why licence sits on axis three, not axis one.

What I prefer: Apache 2.0 and MIT (unproblematic), MPL 2.0 (moderate copyleft, uncritical for wrapping). Where I get careful: AGPL and SSPL — they can leak into SaaS wrappers. What I don't treat as open source at all: BSL, ELv2, Commons Clause (source-available is not open source).

A rule of thumb: projects with a Contributor License Agreement (CLA) on a single-sponsor with commercial strategy are susceptible to license shifts. Projects without a CLA are effectively immune — a unilateral change would need the agreement of every prior contributor.

Put one line in your ADR that explicitly asks: what happens if this component changes its license tomorrow? »We fork« is legitimate, but expensive. »We move to Y« is better, if Y exists. »We hope« is not acceptable.

4. Standards conformance — would a switch affect your consumers?

This axis measures whether the component implements a recognised standard cleanly (OIDC, OpenAPI, the Kubernetes API, OCI, S3) or whether it runs a private variation of a standard. It is the single most important insurance against API lock-in.

A three-question test I run in the ADR meeting:

• Which endpoints do my applications consume?
• Are those endpoints standard-specified or proprietary?
• Is there a second OSS component serving the same standard — and if so, at what maturity?

With OIDC identity providers the line is clean: the OIDC-discovery URL, the authorisation endpoint, and the token endpoint are nailed down in the spec. If your IdP serves these correctly, you can swap it out and no consumer notices — provided you migrate the tenant data properly.

5. Companion gap — how much of your own code around it?

The companion gap is the most common hidden in-house-build quota. If 80% of your stack is mature OSS and 20% is companion code, that is still mainly wrapping. If 40% is companion, it is a hybrid and you should question whether the OSS choice was right at all. If 60% is companion, you've actually built it yourself and just used the OSS as a frame.

The practical metric I use: person-weeks of productive companion work per year.

• Up to 4 person-weeks per year: a very good choice.
• 4-20 person-weeks per year: workable, but expensive.
• More than 20 person-weeks per year: probably the wrong choice — you are de facto building, just inside a foreign architectural frame.

The estimate will be wrong in the first year. In the second and third year it sharpens. If your engineering team defends a wrapping choice, ask for this number. If they don't have one, the axis has not been thought through yet.

6. Migrability — can you also get back out?

This axis is cynical, which is why it comes last. It asks: if everything else holds up, can we still get back out? Low migrability is not an automatic rejection — some of the best choices have high migration costs because their strength lies precisely in how deeply they integrate.

Four concrete ADR questions:

• Where does the data sit — standard DB, proprietary format, internal event store?
• Can the data be exported? In what format?
• Is there a tested migration path to at least one alternative component?
• How long would a realistic migration take with your current resources?

Standards conformance (axis 4) and the companion gap (axis 5) amplify or weaken migrability together. A standard-conforming component with a small companion layer is migratable almost no matter how deep it sits. One with a proprietary API and a large companion is not.

How this plays out in practice: GitOps engine selection

Let's run the matrix through one decision. Setting: a mid-market platform team, 25 engineers, several production Kubernetes clusters, manual roll-outs so far. Task: adopt GitOps. Candidates: FluxCD, ArgoCD, Werf.

Three findings:

First, FluxCD and ArgoCD are both valid. The matrix does not produce a lonely verdict; it leaves two honourable candidates. The tie-breaker becomes context-dependent: if the team wants a UI for self-service roll-outs, ArgoCD wins. If it prefers a composable toolkit of building blocks (source controller, Helm controller, Kustomize controller), FluxCD wins. Both are legitimate.

Second, Werf does not fail on a single killer axis. It scores »3« on axes 1, 2, 4, and 5 — which means it is not a rejection, but it sits a notch below the two leading candidates consistently. In a stack where Werf's strengths (build and deploy from one source) were central, it could still win. In this setting, it doesn't.

Third, the plan-B entry is cheap here. Should the chosen engine drift architecturally in 24 months, switching between FluxCD and ArgoCD is a three-week project, because both use the same standard (Git state plus Helm/Kustomize). That is the direct payoff of strong scores on axes 4 and 6 — it pays out now, not only in a crisis.

What you can take away today

The next wrap-or-build meeting in your team runs differently if you have these six axes on the whiteboard before the meeting. Three to five minutes of honest assessment per axis, and you end up with an ADR that has a score column and a justification column. No point sum — the distribution matters, not the average.

Three rules of thumb that have proven themselves in practice:

• If a value below 3 shows up on axis 1 or 2: wait, pick an alternative, or explicitly flag the ADR as »adoption with risk reservation«.
• If a value below 3 shows up on axis 3 or 4: the choice is possible, but it will produce a licence or migration crisis in two to three years. Both can be acceptable if the stack can absorb them.
• If axes 5 or 6 are low: cut the companion layer cleanly and early, so it stays swappable. Low scores there are not fatal, but they tie up resources long term.

And above all: the matrix measures the component, not the fit. Your stack context still has the last word. A component that aces a cloud-native mid-market stack can fail in a regulated data context, and vice versa. The axes give you the language for an honest conversation — the verdict is still yours to call.