Without a documented breaking change policy, consumers have no way to know which parts of the API are stable and which might change without notice. This matters most at integration time: a consumer building a production integration on an undocumented API is making a bet that the author's implicit stability expectations match their own. When they don't, the consumer's code breaks silently on the next deploy. iso-25010:2011 compatibility.interoperability requires that the API's stability guarantees be explicitly stated — not assumed from silence.
High because undocumented breaking change policies mean consumers cannot make informed integration decisions and have no recourse when changes break their code.
Add an API stability section to your README or API documentation that explicitly defines what is and is not a breaking change:
## API Stability
This API follows semantic versioning. Within a major version:
- Existing fields will not be removed or renamed
- Existing endpoint paths will not change
- Response types will not change
- New optional fields may be added to responses
- New optional parameters may be added to requests
Breaking changes (field removal, type changes, endpoint removal)
will only occur in major version bumps with a minimum 90-day
deprecation notice.
The policy must cover at least: field removal, type changes, endpoint removal, required field additions, and status code changes.
ID: api-design.versioning-evolution.breaking-change-policy
Severity: high
What to look for: Check whether the project documents what constitutes a breaking change and how breaking changes are communicated. Look for: a BREAKING_CHANGES.md, an API changelog, a section in the README about API stability, or versioning documentation that defines the contract. Check for specifics: does it state that removing fields, changing types, or renaming endpoints are breaking changes? Does it define a deprecation timeline?
Pass criteria: Count all documentation files and sections that address API stability. Documentation exists (README section, dedicated doc, or API reference) that defines what constitutes a breaking change and how they will be communicated (version bump, deprecation notice, migration guide). The policy must cover at least 3 of: field removal, type changes, endpoint removal, required field additions, status code changes.
Fail criteria: No documentation about API stability or breaking changes. Consumers have no way to know what might change without warning (e.g., no BREAKING_CHANGES.md, no "API Stability" section in README.md). Quote the actual documentation found (or note its absence).
Skip (N/A) when: The API is explicitly pre-1.0/alpha/beta with a prominent instability warning. Signal: version is 0.x.x, or README/docs prominently state "API is unstable and may change without notice."
Detail on fail: Note what's missing (e.g., "No breaking change policy, no API stability docs, no deprecation timeline. Consumers have no contract guaranteeing field stability across releases."). Max 500 chars.
Remediation: Add an API stability section to your README or API docs:
## API Stability
This API follows semantic versioning. Within a major version:
- Existing fields will not be removed or renamed
- Existing endpoint paths will not change
- Response types will not change
- New optional fields may be added to responses
- New optional parameters may be added to requests
Breaking changes (field removal, type changes, endpoint removal)
will only occur in major version bumps with a minimum 90-day
deprecation notice.