Compatibility Management¶
Essence¶
Compatibility Management is the archetype for keeping change from breaking the ecosystem around it. It applies when old and new versions, rules, procedures, products, schemas, or interfaces must coexist long enough for dependent actors to keep functioning. The intervention is not simply to record that version A came before version B. It is to define whether A and B can interact, who is supported, how migration happens, what gets deprecated, and what counts as unacceptable breakage.
The core intuition is that versions are relational. A new version may be internally coherent and still fail because it collides with older clients, legacy records, prior obligations, or users who cannot migrate instantly. Compatibility management makes that relation explicit.
Compression statement¶
When versions evolve at different speeds, manage compatibility windows, migration rules, and deprecation paths to preserve continuity during change.
Canonical formula: evolving_versions + active_dependencies + explicit compatibility relation + migration/deprecation governance -> continuity under change
When to Use This Archetype¶
Use this archetype when a change creates mixed-version operation. This can happen when a technical platform changes an API, an institution updates policy, a product line introduces a new generation, a data team changes a schema, a curriculum updates requirements, or a legal template is revised while older commitments remain active.
The strongest signal is dependency mismatch: one part of the system changes faster than another part that relies on it. The archetype is especially useful when sudden cutover would strand users, corrupt data, invalidate obligations, break integrations, or destroy trust.
Do not use it merely because something has a version number. If the main need is lineage, provenance, or comparison over time, use Versioned Evolution. If the main need is recovery from a failed change, use Checkpoint and Rollback. If the main need is parallel divergence and recombination, use Branching and Merging.
Structural Problem¶
The structural problem is unmanaged coexistence. Different actors, artifacts, or systems occupy different versions, but the relationship among those versions is implicit. One team may assume everyone has upgraded. Another may depend on old behavior. A third may use a transitional workaround that no one has tested. The system then fails not because any one version is incoherent, but because interaction across versions is underdesigned.
This creates several recurring symptoms: breaking changes appear as surprises, old versions become indefinite maintenance burdens, support commitments are unclear, migration is postponed until crisis, and adapters or workarounds accumulate outside governance.
Intervention Logic¶
Compatibility Management intervenes by turning old-new interaction into an explicit design object. First, identify the active versions and the dependents attached to each. Then define which version pairings are supported, conditional, deprecated, or unsafe. Next, expose breaking-change boundaries and design support windows, migration paths, adapters, negotiation rules, or fallback behavior. Finally, verify the combinations that will actually coexist and revise the compatibility policy as adoption changes.
The intervention is successful when no one has to infer compatibility from hope, habit, or informal memory. Supported combinations are named. Unsupported combinations are named. Transition paths are visible. Retirement of old support is planned rather than accidental.
Key Components¶
Compatibility Management treats the relationship between old and new versions as an explicit design object rather than something to be inferred at runtime by surprised dependents. The Compatibility Rule states which versions, actors, interfaces, records, or procedures can safely interact and at what level — full, partial, conditional, or explicitly unsafe — converting a vague promise into a governed relationship. The Version Relationship Matrix maps those rules across the combinations that will actually coexist: v1 client with v2 server, old form with new eligibility rule, legacy product with new accessory. The Breaking Change Boundary surfaces where a proposed change invalidates existing assumptions, so hidden dependencies become visible before release rather than after a failure.
The remaining components govern how dependents move through change and how long old support persists. The Support Window bounds how long older versions remain supported, protecting dependents from sudden abandonment while preventing legacy support from becoming indefinite by default. The Migration Path makes movement actionable through conversion rules, phased rollout, communication, training, or legal transition provisions. The Deprecation Policy governs safe retirement of old support — notice, alternatives, timelines, and exception handling — turning end-of-life into a planned event rather than an accidental one. An Adapter or Translation Layer bridges genuinely incompatible versions when direct compatibility is infeasible, though adapters need ownership and tests because they can quietly hide semantic loss. Finally, the Compatibility Test Scope verifies that the declared compatibility relation holds in practice, covering real coexistence cases and high-risk dependencies rather than testing the new version alone.
| Component | Description |
|---|---|
| Compatibility Rule ↗ | A compatibility rule states which versions, actors, interfaces, records, or procedures can safely interact. It may define full compatibility, partial compatibility, conditional compatibility, or explicit incompatibility. Without this rule, compatibility becomes a vague promise rather than a governed relationship. |
| Version Relationship Matrix ↗ | The version relationship matrix maps old, current, future, and exceptional versions against each other. It need not always be a literal table, but the system needs a way to reason about combinations: v1 client with v2 server, old form with new eligibility rules, legacy product with new accessory, or previous contract term with current amendment. |
| Support Window ↗ | A support window defines how long, or under what conditions, older versions remain supported. It protects dependents from sudden abandonment while preventing legacy support from becoming endless by default. |
| Migration Path ↗ | A migration path explains how dependents move from one version to another. It may include conversion rules, phased rollout, training, communication, data transformation, or legal transition provisions. Migration path design is where compatibility becomes actionable. |
| Deprecation Policy ↗ | Deprecation policy announces how old versions will lose support. It should include notice, alternatives, timelines, and exception handling. A deprecation policy is not simply a warning; it is the governance of safe retirement. |
| Adapter or Translation Layer ↗ | An adapter or translation layer bridges incompatible versions. It might translate data formats, route old requests to new behavior, map old policy categories to new ones, or mediate between procedures. Adapters are useful, but they can also hide semantic loss, so they need ownership and tests. |
| Breaking Change Boundary ↗ | A breaking change boundary identifies where a change invalidates existing assumptions. It surfaces hidden dependencies before they become failures. In legal, policy, or institutional settings, the boundary may involve rights, obligations, or interpretation rather than technical interfaces. |
| Compatibility Test Scope ↗ | Compatibility test scope defines what must be verified before a compatibility claim is trusted. It should cover real coexistence cases, edge cases, and high-risk dependencies rather than only testing the new version in isolation. |
Common Mechanisms¶
Backward compatibility policies require newer versions to continue accepting older inputs, clients, records, or expectations for a defined period. They implement the archetype by protecting legacy dependents while migration proceeds.
Semantic versioning signals expected compatibility through version numbers. It is useful as a communication mechanism, but it is not the archetype itself because a version number cannot guarantee support, migration, or evidence.
API versioning exposes multiple interface versions so clients can move at different speeds. This is a domain-specific mechanism for the broader old-new interaction problem.
Schema migration transforms data or classifications from one version to another. It implements compatibility when records, analytics, or workflows need to survive structural change.
Protocol negotiation lets parties discover a mutually supported version or mode before interacting. It is valuable when compatibility cannot be assumed in advance.
Rolling upgrades gradually introduce change while old and new versions coexist. They depend on compatibility management because mixed-version states must be safe during rollout.
Migration guides help dependent actors move from old to new. They make the compatibility policy usable rather than merely declared.
Compatibility matrices display supported and unsupported combinations. They are representation artifacts, not the archetype itself.
Adapter layers mediate incompatible versions or formats. They are powerful but risky if they obscure meaning loss or become unmanaged sources of truth.
Compatibility test suites verify that the declared compatibility relation holds in practice.
Parameter / Tuning Dimensions¶
Compatibility management has several tunable dimensions. The breadth of support determines how many versions or combinations remain supported. The duration of support determines how long old versions persist. The strictness of compatibility determines whether compatibility means full equivalence, partial function, safe degradation, or merely non-corruption. The migration burden determines how much work is placed on maintainers versus dependents. The adapter depth determines whether compatibility is achieved through shallow translation, deep semantic mapping, or direct shared behavior. The deprecation threshold determines what evidence is needed before old support can end.
Tuning is not purely technical. Longer support windows can be more equitable but more expensive. Strict compatibility can preserve trust but delay necessary change. Fast deprecation can reduce maintenance burden but strand actors with less capacity to migrate.
Invariants to Preserve¶
The central invariant is that supported interactions should not surprise participants. If a version combination is supported, it should preserve required meaning, safety, integrity, authority, and obligation. If it is unsupported, that fact should be visible before harm occurs.
Other invariants include discoverability of support status, boundedness of compatibility commitments, migration feasibility, accountability for adapters, and transparent deprecation. Compatibility management should preserve continuity without pretending that every old behavior deserves indefinite preservation.
Target Outcomes¶
The desired outcomes are fewer breaking changes, safer migration, clearer support commitments, reduced legacy ambiguity, and more predictable evolution. Done well, compatibility management lets a system change without forcing every dependent actor to move at the exact same moment.
It also improves trust. Users, clients, institutions, and dependent teams can plan because they know what will keep working, what will stop working, and how to move.
Tradeoffs¶
The archetype trades simplicity for continuity. Supporting multiple versions increases maintenance burden, test scope, documentation needs, and decision complexity. It can also preserve harmful legacy assumptions if deprecation is too timid.
At the same time, refusing compatibility can shift the cost of change onto dependents who lack power or capacity. The art is to preserve enough continuity for legitimate dependence while making old support bounded, visible, and reviewable.
Failure Modes¶
A common failure mode is the silent breaking change, where hidden dependencies were never mapped and old users discover breakage only after release. Another is infinite legacy support, where old versions persist because no one defined retirement criteria. A third is the false compatibility promise, where versions are labeled compatible even though their semantics differ in important edge cases.
Adapters can drift into unmanaged infrastructure. Deprecation can happen too early and strand dependents. Compatibility can also become paralysis, blocking needed evolution because any change might break someone. The mitigation is explicit scope, support windows, migration evidence, breaking-change review, and honest classification of partial or conditional compatibility.
Neighbor Distinctions¶
Versioned Evolution tracks and governs change lineage. Compatibility Management governs safe interaction across active versions. A changelog is not enough when old and new must coexist.
Checkpoint and Rollback prepares a return path after failure. Compatibility Management tries to prevent mixed-version breakage during normal evolution.
Branching and Merging governs parallel divergence and recombination. Compatibility Management governs interaction among versions, even when there is no branch to merge.
Mapping Reconciliation aligns different representations. Compatibility Management may use mapping reconciliation, but it adds support windows, deprecation, migration, and breakage governance.
Decoupling via Interface is a neighboring idea and a proposed prime-like concept in this draft. Compatibility Management may use interface decoupling, but it is specifically about cross-version coexistence and support.
Variants and Near Names¶
Important recognized variants include Backward Compatibility Management, which protects old dependents from new-version breakage; Forward Compatibility Management, which helps older versions tolerate future extensions; Adapter-Mediated Compatibility, which uses translation or wrapper layers; Migration Window Compatibility, which bounds compatibility to a transition period; and Negotiated Protocol Compatibility, which selects a mutually supported mode at interaction time.
Near names include compatibility governance, version compatibility management, mixed-version operation, breaking change management, backward compatibility, API version compatibility, and support lifecycle management. Most of these are aliases, domain names, or mechanism names rather than separate top-level archetypes.
Cross-Domain Examples¶
In software, an API provider can support old and new endpoints while publishing migration guides and compatibility tests. In data governance, a schema migration can preserve old fields during a support window while downstream dashboards migrate. In public policy, old and new eligibility rules can coexist through transitional provisions. In product operations, parts and accessories can be marked compatible or incompatible across generations. In education, old and new curriculum standards can be bridged so students are not stranded mid-program. In legal drafting, amendments can specify how prior obligations interact with revised clauses.
Across all examples, the common structure is not software-specific. A change creates multiple active versions, and the solution is to govern their relationship.
Non-Examples¶
A simple changelog is not Compatibility Management if no old-new interaction must be supported. A one-time conversion script is not the archetype if there is no continuing coexistence or support policy. A rollback plan is not compatibility management if the response to failure is simply to return to a known-good state. A branch merge is not compatibility management if the core problem is recombining divergent work rather than supporting mixed-version interaction.