# A patch for one customer can break three others

> Semantic versioning, changelogs and maintenance windows tell each customer in advance when they will be upgraded and what will change.

Original: https://fdetimes.net/en/guides/versioning-changelogs-maintenance-windows-multiple-clients/

On Friday you fix a time-zone bug in a connector for customer A. The patch is small, every test is green, and you push it to all five customers who share the connector. On Monday morning there are three tickets: customer B's report is off by a day, customer C's pipeline throws a parse error, and customer D asks why nobody warned them.

The code has no bug. What went wrong is a release process that never accounted for one change reaching many customers, each with its own operating rhythm and its own tolerance for risk.

For FDEs this happens sooner than many expect. Once an integration you wrote for the first customer is carried over to a second and a third, you are maintaining a product, even if nobody calls it one yet. Three tools are worth mastering: version numbers, changelogs and maintenance windows.

## A version number is a promise, not a sequence number

Semantic Versioning 2.0.0 defines three numbers with three meanings. Increment MAJOR for incompatible API changes. Increment MINOR when adding functionality in a backward-compatible way. Increment PATCH for backward-compatible bug fixes.

The hard part is that "compatible" has to be read from the customer's point of view. Apply it to the connector above, currently at version 2.3.1:

| Change | What the customer sees | New version |
|---|---|---|
| Fix a crash on empty files | Something broken now works | 2.3.2 |
| Add an optional `region` field | More data, the old stays the same | 2.4.0 |
| Rename `customer_id` to `account_id` | Running queries break | 3.0.0 |
| Switch timestamps from local time to UTC | Same field, different values | 3.0.0 |

The last row is the Friday patch. To you it was a bug fix, but customer B had built reports on the old behaviour. When a change alters results a customer depends on, the safe course is to treat it as MAJOR, or to add a configuration flag so the customer can switch on the new behaviour themselves.

SemVer has one more rule that many teams forget: once a version is released, its contents must not change. Any modification must go out as a new version.

When several customers pin 2.3.1, quietly rebuilding and overwriting the 2.3.1 tag means two customers both run "2.3.1" but are running two different things.

When an incident hits, you will no longer know who is running what.

**Key point:** A version number is a promise to the customer, not a label the team sticks on for convenience.

## Let each customer choose its upgrade date

Stripe is an example worth studying. The first time an account calls the API, that account is pinned to the latest version at the time. From then on, the customer upgrades on its own schedule, not Stripe's.

Behind the scenes, each backward-incompatible change is wrapped in a version change module. That keeps old versions working without compatibility logic spreading through the codebase.

Stripe now releases a new version monthly with no breaking changes, and twice a year ships a major release that contains breaking changes. Webhook endpoints can also be pinned to their own version, so a customer can upgrade one integration at a time.

An FDE maintaining a connector for a handful of customers does not need to build a system like that. One configuration line per customer recording the version they run is enough.

When renaming `customer_id` to `account_id`, do not scatter `if version < 3` everywhere. Write a single adapter function that converts the new format back to the old one for customers still on 2.x.

When the day comes to drop support for 2.x, you delete exactly one file.

## Say clearly how far back you support

Version pinning without limits leaves you maintaining ten versions at once. Kubernetes solves this with a public policy: the kubelet may be at most three minor versions older than kube-apiserver. Release branches are kept only for the three most recent minor releases, and from 1.19 onwards each release gets roughly a year of patches.

Because of that number, customers know how much time they have and can upgrade piece by piece rather than changing everything in one night.

Write a similar paragraph for your connector, for example: "Security fixes for the current minor release and the two before it; an old major release is supported for six months after the new one ships." The exact numbers are your team's call, as long as they are written down and the customer has read them.

## Changelogs are written for the customer's operators

Keep a Changelog opens with a principle: changelogs are for humans, not machines. Pasting raw `git log` output is not a changelog. The reader here is the customer's operations engineer, and they need to know only two things: do they have to do anything, and by when.

The standard groups changes into fixed categories, including Deprecated for features about to be removed and Removed for features already gone. It also sets a minimum: if you do nothing else, at least list deprecations, removals and every breaking change. For the connector above, a good changelog entry looks like this:

```markdown
## [3.0.0] - 2026-12-01
### Changed
- BREAKING: `customer_id` renamed to `account_id`.
  Action required: update queries that read this field. 2.x keeps receiving bug fixes until 2027-06-01.
- BREAKING: timestamps are returned in UTC instead of local time.
### Deprecated
- The `legacy_auth` parameter, to be removed in 4.0.0.
### Fixed
- No longer crashes when the input file is empty.
```

Every BREAKING line comes with what the customer must do and a deadline. Had customer D read an entry like this before Friday, there would have been no third ticket.

## A maintenance window only sets the start time

The last piece is when to deploy. Amazon RDS uses a weekly 30-minute maintenance window. If you do not choose one, RDS assigns a random day of the week. AWS documentation also states plainly that maintenance is not guaranteed to finish before the window closes and may run past its end time.

Picture customer C giving you a window from 02:00 to 02:30 on Sunday morning. On staging, the field-rename migration takes 40 minutes. If it runs as planned, at 02:40 the system is still mid-task while the customer's on-call shift has gone home.

There are two sensible options: ask for a longer window, or split the migration into a background step that runs a few days earlier, leaving only the flag switch for the window itself.

RDS has another detail worth copying. For mandatory upgrades, after the mandatory apply date RDS may upgrade outside the window the customer chose. Moving the window does not mean postponing forever. When you drop support for 2.x, you need a date like that too, announced to customers early and repeated in the changelog.

## The most common mistakes

The most common mistake is classifying by the size of the diff rather than its impact on the customer, as with the UTC patch at the start. The second is overwriting an old tag to save time, exactly what SemVer forbids. The third is treating the window's closing time as a guaranteed finish, so nobody is on call when the work overruns.

The fourth gets less attention: deploying to all five customers at once. Roll out in order, starting with the customer most tolerant of risk or with a customer's staging environment, wait for one full data cycle to complete, then continue.

## Putting this skill on your CV and in interviews

A CV line such as "maintained a versioned connector for multiple customers, with a support policy and a public changelog" shows recruiters you have lived with the consequences of your own code. If you can, link to that changelog or support-policy page.

When reading FDE job ads, look for phrases such as "rollout", "upgrade" or "multi-tenant", then ask in the interview how many customers the team ships to and at what cadence. Telling the story of a time you wrongly filed a change as PATCH, and how you fixed the process afterwards, is usually more convincing than any definition.

Customers do not demand that you never make mistakes. They need to know in advance when you will change what, and, when something does go wrong, to have a way back to the previous version.

**Try this week:**

- Take the last 10 commits of a connector or SDK you maintain, classify each as MAJOR, MINOR or PATCH, and compare against the version numbers actually released
- Rewrite the changelog for your latest release under Added, Changed, Deprecated, Removed and Fixed, putting Deprecated and Removed at the top
- Write a one-paragraph version support policy stating which releases you still patch and until when, then send it to your team lead for feedback

## Sources

- [Semantic Versioning 2.0.0](https://semver.org/)

- [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [How API versioning works](https://docs.stripe.com/api-versions)

- [Version Skew Policy](https://kubernetes.io/releases/version-skew-policy/)

- [Maintaining a DB instance - Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html)
