breaking-change-reviewlisted

# Breaking Change Review > Merge verdict or it did not happen. ## Overview Classify every contract delta, demand migration notes for breaks, emit **approve / request-changes / version-bump / waiver**. ## Catalog (shipped APIs) **Usually breaking** | Category | Examples | |----------|----------| | Surface | Remove endpoint/method | | Shape | Remove/rename field; type/nullability tighten | | Enums | Remove value | | Auth | Newly required auth; narrowed scopes | | Protocol | Success status clients branch on; parsed error codes | | Validation | Reject previously accepted requests | | Semantics | Same schema, different meaning | | Pagination | Cursor format change; surprising default size cuts | **Usually non-breaking** - Optional response field, new endpoint, optional request field with server default - New enum value (if clients must tolerate unknowns - document) - Relaxed validation, new documented error code for a new failure mode ## Steps 1. **Before / after** - OpenAPI files, or reconstruct public shapes from code. 2. **Optional machine assist** (when both sides are OpenAPI 3.x YAML/JSON): ```bash python scripts/openapi_breaking_diff.py old.yaml new.yaml # exit 0 = no hard breaks detected; exit 2 = hard/semantic breaks python scripts/openapi_breaking_diff.py old.yaml new.yaml --format json ``` Treat tool output as a **draft delta list**, not the final verdict. Confirm false positives (complex `oneOf`/`allOf`, external `$ref`). 3. **Atomic deltas