# Breaking change policy documented

- **Pattern:** `ab-000366` (`api-design.versioning-evolution.breaking-change-policy`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000366
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000366)

## Why it matters

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.

## Severity rationale

High because undocumented breaking change policies mean consumers cannot make informed integration decisions and have no recourse when changes break their code.

## Remediation

Add an API stability section to your README or API documentation that explicitly defines what is and is not a breaking change:

```markdown
## 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.

## Detection

- **ID:** `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:

  ```markdown
  ## 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.
  ```

## External references

- iso-25010 compatibility.interoperability
- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000366