You own a widely-used library. What is your policy on letting consumers subclass your classes, and how does that policy affect versioning and long-term evolution?

## Why the question matters at library scale Inside one repo, a bad inheritance decision costs a refactor. In a published library it costs a **major version**, because the set of subclasses is unknown, unbounded, and outside your build. The API surface you actually committed to is much larger than the one you documented. ## What subclassing silently publishes Once a concrete class is open: 1. **Self-call structure.** "`process()` calls `validate()` then `persist()`" is now observable behavior someone overrides against. Reordering or inlining those calls breaks them, invisibly and at runtime. 2. **Protected members.** Fields, methods, their types, nullability, and lifecycle are API — with implementation detail baked in. Renaming a protected field is breaking. 3. **Constructor sequencing.** If any constructor calls an overridable method, subclasses observe partially-initialized state; that ordering is now frozen. 4. **Invariants and thread-safety assumptions** subclasses rely on. 5. **Method presence itself.** Adding a method to an open class can accidentally collide with a subclass's existing method (accidental override), silently repurposing it. Compilers requiring an explicit override keyword turn this into a compile error — better, but still a source-breaking change for consumers. None of this appears in your API docs, yet all of it constrains you forever. ## The policy **Default: closed.** - Mark classes `final` / `sealed` / non-`open` by default (some languages are closed by default — lean into it). - Where a closed set of variants is meaningful, use a **sealed hierarchy**: consumers can match exhaustively, you keep the right to know all cases. Note the reverse obligation — adding a case to a sealed type breaks consumers' exhaustive matches, so treat that as a minor/major decision consciously. **Extension seams you publish instead:** - **Interfaces to implement** for pluggable behavior (`interface RetryPolicy`, `interface Serializer`) — you depend only on the contract you wrote. - **Strategies/functions injected** at construction or per call — smallest possible contract, trivially testable. - **Listeners / hooks / middleware chains** for cross-cutting concerns; you control invocation points and can add new ones without breaking anyone. - **Builders and configuration objects** for variation that is really data, not behavior. - **Decorator-friendly design**: publish an interface for everything a consumer might want to wrap, so wrapping works without subclassing. **When inheritance is the intended seam** (framework lifecycle bases, skeletal implementations like an abstract adapter that turns a 12-method interface into 3), pay the tax explicitly: - Document the **self-use pattern** precisely, and treat it as frozen contract. - Expose a **minimal set of protected hooks**; make everything else final. Template Method: you own the skeleton, they own named steps. - **Never invoke overridable methods from constructors/initializers**; use a post-construction `init()` the framework calls. - Prefer **abstract methods over optional overrides** where a step is mandatory — it makes the contract explicit at compile time. - **Write subclasses yourself in your own test suite** so internal refactors fail your CI, not your users' production. ## Interface evolution — the reciprocal trap Closing classes pushes contracts into interfaces, which have their own compatibility rule: **adding a method to a published interface breaks every implementer**. Mitigations: default/defender methods with a sane implementation; a companion abstract skeletal class consumers may extend (documented for inheritance, so the tax is paid deliberately); or a `sealed` interface when you don't want external implementations at all. Decide up front whether an interface is **consumer-implemented** (evolve conservatively, use defaults) or **library-implemented** (you can add freely, consumers only call it) — and say which in the docs. ## Binary vs source compatibility For compiled/distributed artifacts, distinguish: - **Source compatibility** — consumer code still compiles. - **Binary compatibility** — pre-compiled consumer artifacts still link/run without recompilation. Inheritance-related changes frequently break binary compatibility even when source looks fine (changing a protected field's type, changing a method's declared throws/return in a way linkers care about, adding an abstract method). Automated checks (binary-compatibility validators, API-diff tools in CI) are the practical control; the policy without enforcement erodes. ## Migration for an already-open library You usually inherit an open codebase. A workable sequence: 1. **Inventory** which classes are actually subclassed by consumers (telemetry, code search across the ecosystem, issue history). 2. **Freeze** the rest at the next major: mark final, announce with a deprecation window and a replacement seam. 3. **Introduce the replacement seam first** (interface + strategy injection), migrate your own internals to it, then deprecate the inheritance path. 4. **Keep a thin open shim** for the highest-value cases with an explicit, documented hook contract. 5. **Add API-compatibility checks to CI** so the policy is enforced mechanically, not by reviewer memory. ## The one-liner Opening a class later is a **non-breaking** change; closing one is **breaking**. Therefore: start closed, open deliberately, and only where you're willing to freeze your internal call structure for the life of the major version.