| name | anticipating-interface-stability |
| description | Assess interface stability and predict breaking changes by distinguishing stable contracts from volatile implementation details. Use when: (1) asked to evaluate dependency on an interface, library, or API, (2) code assumes interface behavior beyond documented contracts, (3) depending on observed behavior rather than guaranteed contracts, (4) architectural decisions hinge on interface stability and long-term maintenance costs. |
Interface Stability
Evaluate how stable an interface is and predict which aspects might change, helping me anticipate breaking changes before depending on fragile contracts.
Instructions
When assessing interface stability, I examine what's promised versus what's incidental to separate stable abstractions from parts likely to evolve.
-
Examine the explicit contract - I identify what's formally documented and versioned, recognizing that written promises create stronger stability commitments than informal behavior because breaking documented contracts visibly harms users who trusted the documentation.
-
Distinguish abstraction from implementation - I separate what the interface conceptually promises from how it achieves that promise, understanding that abstractions tend to stabilize while implementation details evolve, so depending on abstract concepts is safer than depending on concrete mechanics.
-
Identify stability signals - I look for versioning schemes, deprecation warnings, semantic versioning adherence, and documentation depth as indicators of stability commitment, since these signals reveal how seriously the maintainers treat breaking changes and backward compatibility.
-
Detect fragile assumptions - I find dependencies on undocumented behavior, implementation details, or timing characteristics that weren't guaranteed, recognizing these as brittle points where my code might break even if the interface's explicit contract doesn't change.
-
Assess change likelihood - I evaluate which aspects face evolutionary pressure by considering what problems the current design doesn't solve well, what users complain about, and what architectural mismatches exist, since these pressures predict where breaking changes will eventually occur.
-
Map breaking change risk - I identify which potential changes would actually break my usage versus which would be backward compatible, understanding that my stability risk depends not just on what might change but on whether those changes affect how I'm using the interface.
Examples
Assessing function signature stability
I'm using a utility function parseDate(dateString) that returns a Date object. I examine the documentation and find it's in a v1.x library with semantic versioning. The explicit contract promises parsing ISO 8601 strings, but I notice my code depends on the function throwing exceptions for invalid input, which isn't documented. I recognize that exception behavior is an implementation detail likely to change, perhaps becoming error return values in v2.x. The parsing of ISO 8601 is the stable abstraction, while error handling is volatile. I assess high risk if I depend on catching exceptions, so I add explicit validation before calling parseDate rather than relying on exceptions for flow control. The documented return type (Date object) is stable, but undocumented behavior (exceptions) is fragile.
Assessing component API stability
I'm integrating a third-party DataTable component in my React app. I examine its prop interface and notice it accepts data, columns, and onRowClick as documented props, but I discover it also works if I pass className even though that's not in the type definitions. I assess that data and columns are core abstractions unlikely to change, while onRowClick might evolve to a more sophisticated event system since it only provides row data, not column or cell context. The undocumented className passthrough is highly volatile, probably an implementation accident that could disappear in any version. I also notice the component is at v0.8, signaling pre-stability where breaking changes are expected. My assessment is that depending on the core data/columns contract is relatively safe, onRowClick might change signature, and className passthrough will definitely break. I decide to wrap the component in my own abstraction to isolate my app from these predicted breaking changes.
Assessing service contract stability
I'm designing a system that will depend on a partner's payment processing API. I examine their API documentation and find they use URL-based versioning (/v3/charges) with a stability policy promising v3 support for minimum 24 months. The contract specifies required fields for charge creation (amount, currency, source) and optional fields for metadata. I notice our integration depends on the API returning charges in creation-time order, but this ordering isn't documented in the contract, just observed in current behavior. I assess that required fields are highly stable since changing them would break all integrations, versioning signals strong backward compatibility commitment for v3, optional fields might expand but existing ones should remain optional, and the undocumented ordering behavior is fragile and likely to break when they implement pagination or filtering. I also examine their changelog and see they've introduced breaking changes between major versions but maintained strict compatibility within versions, which validates their versioning signal. My stability assessment is that I can safely depend on the versioned endpoint and required fields, should anticipate new optional fields appearing, and must not rely on ordering guarantees that aren't in the contract. I design my system to work with unordered charges and plan for eventual pagination, even though current behavior doesn't require it.
