What semver bump does my API change need?
A mixed diff, classified by the merge gate into one answer.
Delimit ran over the Twilio Messaging v1 OpenAPI between the twilio-oai 2.5.0 release (2025-09-04) and 2.6.9 (2026-05-07). 107 changes across nine change types: 9 breaking, 96 additive. The classifier resolves the whole set to a single bump.
twilio/twilio-oaiis public; 2.5.0 and 2.6.9 are real tagged releases.- This is not a defect report and Twilio is not a Delimit customer. We use the diff only to show how the classifier behaves on a mixed change set.
- Reproducible byte-for-byte (command at the end).
The problem
"What semver bump does my API change need?" sounds like a lookup and is actually a judgment across the whole diff. A release that adds 96 harmless things and changes 9 in a breaking way is not a minor release; it is a major one, because a single breaking change forces the bump. Get it wrong in the additive direction and you ship a breaking change under a minor version number, which is how consumers get surprised.
An AI assistant asked to "pick the version" will often reason from the majority of the diff, which is additive here, and land on minor. The merge gate reasons from the tiers instead.
The setup
Pass the current version and the gate returns the classified change set plus the recommended next version.
# .github/workflows/api-merge-gate.yml
name: API merge gate
on: [pull_request]
jobs:
delimit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: delimit-ai/delimit-action@v1
with:
spec: spec/json/twilio_messaging_v1.json
current-version: "1.0.0"What free Delimit detects
Every change is assigned a change-type and a semver tier. 9 changes land in the major tier, 98 in the minor tier. The counts below are the real distribution for this diff.
| Change type | Count | Tier | What it is |
|---|---|---|---|
| response_type_changed | 4 | major | response schema shape changed on USA2P compliance reads |
| type_changed | 4 | major | declared type of a schema member changed |
| additional_properties_tightened | 1 | major | a schema stopped allowing extra properties |
| optional_field_added | 48 | minor | new optional response/request fields |
| enum_value_added | 42 | minor | new accepted enum values |
| optional_param_added | 5 | minor | new optional query/path parameters |
| nullability_added | 2 | minor | a field may now be null (additive for readers) |
| endpoint_added | 1 | minor | one new route |
No change in this diff fell in the patch tier (documentation-only or deprecation-flag changes). The taxonomy still defines that tier; this particular release just did not exercise it.
The classification rule
The rule is the standard semantic-versioning precedence: the bump is the highest tier present in the change set. Nine major-tier changes are enough on their own; the 96 additive changes cannot pull the answer down. So a release that is 90% additions is still a major release, and the gate recommends the next major version.
Why a generic AI review misses it
Ask a model "what version should this be?" and it weighs the diff narratively. When 96 of 107 changes are safe additions, the story reads "big additive release," and the model reaches for minor. The nine breaking changes are a rounding error in prose and a decisive factor in semver. The two readings disagree, and only one of them is the rule.
The gate does not weigh the diff. It classifies each change, takes the maximum tier, and returns the same answer every run.
Reproduce locally
# Install the CLI npm install -g delimit-cli # Clone the spec repo git clone https://github.com/twilio/twilio-oai cd twilio-oai # Extract the two tagged releases git show 2.5.0:spec/json/twilio_messaging_v1.json > /tmp/old.json git show 2.6.9:spec/json/twilio_messaging_v1.json > /tmp/new.json # Run the merge gate with a current version to get the bump delimit lint --current-version 1.0.0 /tmp/old.json /tmp/new.json
If your bytes differ from this report, raise it on the Delimit repo.
Free detects. Pro proves.
Free Delimit is the merge gate: it classifies the diff and tells you the bump on every pull request. Install delimit-cli or add the delimit-ai/delimit-action to CI. Free for individual maintainers.
Pro turns the version verdict into a signed, replayable attestation: a portable record of the classified change set and the recommended bump that a reviewer or downstream consumer can verify without rerunning the gate. Pro tier $10/month for teams.