Your Changelog Says Nothing Broke, and Your Customers' Integrations Disagree
A customer's order-sync integration has run without a problem for two years. On Tuesday morning it starts dropping orders. Their engineer spends a day tracing it and finds the cause: your API began returning a new value, partially_refunded, in the order status field. Their code handled the four statuses your docs listed and threw an exception on anything else. They open a ticket asking what changed. Your support team points them to the changelog, which says, in its entirety: "Improved refund handling."
From your side, nothing broke. You added a value; you didn't remove or rename anything. From the customer's side, a stable integration failed in production with no warning, and the only record of the change told them nothing they could act on.
That gap is the real problem. It isn't that your API changes. Every useful API changes. It's that you and your customers have different definitions of "breaking," and neither definition is written down anywhere they can read it.
"Non-breaking" is a promise you have to publish
Every API team works from some private idea of what counts as safe to ship without a version bump. The trouble is that the line isn't obvious, and reasonable platforms draw it in different places.
GitHub's REST API documentation lists what it treats as breaking: removing an operation, removing or renaming a parameter or response field, adding a new required parameter, making an optional parameter required, changing a type, removing enum values, adding a new validation rule to an existing parameter, and changing authentication or authorization requirements. It lists adding enum values as additive, a change that shouldn't break an integration.
Stripe publishes its own list of backward-compatible changes, including adding new properties to responses, changing the order of properties, adding new event types, and changing the length or format of opaque strings such as object IDs and error messages. Then it tells integrators what that means for their code: design your integration to ignore unfamiliar fields and event types, and make sure your webhook listener handles event types it doesn't recognize.
That second part is the point. A compatibility policy isn't only a list of what you're allowed to do. It's instructions to your customers about how to write code that survives your future releases. If you don't publish it, a developer who writes a strict switch over your status values isn't being careless. They're coding to the only contract they can see, which is the list of values in your reference today.
Write the compatibility policy first
Before you fix a single changelog entry, write one page that answers these questions:
- What changes do you ship without a new version? Be specific: new endpoints, new optional parameters, new response fields, new enum values, new event types, reordered fields, longer IDs.
- What do you consider breaking? Removals, renames, type changes, new required inputs, and stricter validation at a minimum. If you treat a changed default as breaking, say so.
- What should client code assume? Ignore unknown fields. Treat enums as open sets with a fallback case. Don't parse IDs or error message text. Handle unrecognized event types without failing.
- How much notice do you give before a breaking change, and how long do old versions stay supported? GitHub, for example, commits to supporting the previous REST API version for at least 24 months after a new one is released. Your number may be different. It needs to exist.
- Where do changes get announced? One canonical place, not a mix of release notes, blog posts, and emails that each say something slightly different.
Then link that page from your quickstart and your SDK docs, not just from the changelog. The customer who needs it most is the one writing their first integration, long before your next release.
Write changelog entries for the person maintaining the integration
Most API changelogs are written by the team that made the change, for the team that made the change. "Improved refund handling" means something to the engineer who shipped it. To a customer, it's a sentence with no endpoint, no field, and no action.
A useful entry answers what an integrator needs to know in about thirty seconds:
- What changed, named precisely: the endpoint, field, parameter, event type, or error code.
- Old behavior and new behavior, side by side when behavior changed.
- Who is affected, such as "integrations that read
statuson order objects." - Whether action is required, stated explicitly, even when the answer is "no action required."
- When it takes effect, with a date, and whether it's already live.
Here's the order-status entry rewritten:
### 2026-11-03 · Orders API · Additive
Added `partially_refunded` as a value of `status` on Order objects.
Previously, a partially refunded order kept the status `paid`.
Affects: integrations that branch on Order `status`.
Action: none required if your code handles unrecognized status
values. If it rejects unknown values, add a case for
`partially_refunded` or a default branch.
That entry would have taken the team five extra minutes to write. It would have saved the customer a day of debugging and saved your support team a ticket. And because it's dated and labeled, a customer's engineer can scan a quarter of changes and see what touches them.
Classify every change before it ships
The other half of the fix is process. If nobody decides whether a change is breaking until a customer reports it, the changelog will always be written after the fact.
Add a compatibility label to your release workflow: additive, behavior change, deprecation, or breaking. Make it a required field on the pull request or release ticket for anything that touches the public API, and make the changelog entry part of the same change. The reviewer's question becomes concrete: "Does this match our published policy, and does the entry tell a customer what to do?"
The labels also tell you when a change needs more than a changelog line. A deprecation or a breaking change needs a migration path, which I covered in Your Customers Are Still on v1 Because Nobody Wrote the Migration Guide. The changelog announces the change. The migration guide tells customers how to get through it.
Audit your changelog this week
You don't need outside help to see how big the problem is:
- Read your last ten changelog entries as a customer. For each one, could you tell which endpoint changed and whether you need to do anything? Count the ones where you couldn't.
- Search support tickets for "what changed," "stopped working," "new value," and "unexpected field" over the last six months. Match each ticket to a release.
- Ask three engineers where the line between breaking and non-breaking is. If you get three answers, you don't have a policy yet.
- Check your reference for enum fields that don't say whether new values may be added. Each one is a future support ticket.
- Look for changes that never made it into the changelog at all, especially stricter validation and changed defaults. Those are the ones customers find in production.
Why this takes an engineer
Writing a good changelog entry means knowing what the change does to someone else's code. That requires reading the diff, understanding how a typical client consumes the field, and recognizing that a new enum value or a tighter validation rule will break code that the team never sees. It's reading code first and writing second, and that's the work I've done for decades.
If your customers keep finding out about API changes from their own error logs, I can help. I'll draft your compatibility policy, rewrite your changelog template, and set up a review step so every public change ships with an entry integrators can act on. You can reach me through the contact page.