Worked example: reading Stripe's changelog

Stripe is a useful worked example because its change process is unusually explicit: dated API versions, a public changelog, and an upgrade guide that describes what moves between versions. The same reading method applies to providers with less structure — you just have to infer more.

How Stripe versions its API

Stripe versions the API by date. An account has a default version, and a request can pin a different one for that call alone. That means the version in effect is a combination of account configuration and request code — two places, neither of which is your package manifest.

This is why an integration can keep working for months and then break when someone upgrades the account default, or when Stripe retires an old version. The changelog entry that described the behavioural difference may be years old by the time it reaches you.

Anatomy of a changelog entry

A typical Stripe changelog entry carries a release date, the API version it belongs to, a short heading, and prose describing the change. Reading it as an engineer means extracting five things:

• The affected surface. Which endpoint, object or field does the entry name? If it names an object, which operations on that object change?
• The direction of the change. Is something added, removed, renamed, or is the meaning of an existing field different?
• Whether it is breaking under your usage. A removed field is breaking only where it is read; an added field is usually safe.
• The version boundary. Which dated version introduced it, and which versions still behave the old way?
• The migration action. Some entries name a replacement field or endpoint; some only describe new behaviour and leave the migration to you.

Applying one entry to a repository

Take an entry that changes how a response field is populated. The workflow is the same every time:

# 1. Find the call sites, not just the SDK import
rg -n 'api\.stripe\.com|stripe\.(charges|customers|subscriptions)'

# 2. Find reads of the specific field
rg -n 'invoice\.settings|payment_intent\.charges'

# 3. Check whether the API version is pinned in requests
rg -n 'Stripe-Version|stripe_version|apiVersion'

Step one answers which repositories are exposed. Step two answers which call sites actually depend on the changed behaviour. Step three answers the question most teams skip: is this request even using the version the entry describes? A request pinned to an older version is not affected yet — but it will be when that version is retired, so the retirement date belongs in the ticket.

The two dates that matter

• The release date of the version that introduced the change, which tells you how long the old behaviour has been the old behaviour.
• The retirement date of the version you are on, if the provider publishes one. This is the date that turns a latent risk into a deadline.

Teams that track only the first date accumulate a backlog of changes they have not evaluated. Teams that track the second date get a work queue with an expiry, which is far easier to schedule.

What this example generalises to

Replace Stripe with GitHub, Twilio, Slack or AWS and the method holds: find the version boundary, find the surface, find the call sites, then decide. What changes is the amount of help the provider gives you. Stripe publishes dated versions and an upgrade guide. GitHub publishes dated REST versions and a changelog. Some providers publish prose in a blog post with no version boundary at all — in which case the only reliable date is the publication date, and the safe assumption is that the change may already be live.