API churn

What it means

API churn tracks additions, removals, renames, type changes, or semantic changes in a public contract. High churn can indicate evolving requirements or an unstable boundary and may impose migration cost on consumers. The measurement should distinguish compatible additions from breaking changes.

Example

A client library adds a field every week but rarely removes one. A separate count of breaking changes shows whether the apparent churn is actually disruptive.

Limitations

Churn does not prove poor design because early-stage products may need rapid evolution. A stable interface can still encode a harmful contract. Include consumer impact, deprecation periods, and semantic changes where possible.

How to use the signal

Record consumer migrations alongside the count, because a small number of breaking edits can create more work than many compatible additions.

Compare compatible additions separately from breaking edits so the trend reflects consumer disruption rather than raw activity.

Weave can help relate breaking API changes to review iterations, deployment frequency, and rework. Use schema or API diff tooling for the change classification and Weave for workflow context.