What we adopt from a Craft release, and what we skip

Every Craft release comes with a changelog and an expectation that you'll read it, get a bit excited, and refactor something. We read them and refactor almost nothing.

The reason is practical. We host most of what we build, so every upgrade is one we personally have to be awake for at seven in the morning if it goes badly. Over time that's turned instinct into a written policy, and it's short enough to set out here.

Adopt immediately: anything that reduces what we maintain

If a release moves something out of our code and into the CMS, we take it the same week. Every line of custom code we delete is a line nobody has to understand in three years, and a line that can't break during somebody else's upgrade.

Most teams under-rate this category, because deleting code doesn't feel like progress. There's nothing to demo at the end and no new feature to point at. But a codebase that shrinks while the site does more is one that stays maintainable after whoever wrote it has moved on.

In practice: when Craft absorbs something we used to build by hand, we schedule the removal into the next hosting window rather than waiting for a reason, because the reason never turns up on its own.

Adopt on the next build: anything that changes the shape of a content model

New field behaviour, new relationship options, new ways of structuring entries. These are often the most useful things in a release, and we won't retrofit them into a site that already works.

A content model is a contract with the person who edits the site every day. They've learned where things are, built habits, and probably written their own notes. Rewriting that because a tidier option has appeared is our excitement, not their problem to absorb.

So it goes into the next new build, where the editor is learning the model for the first time anyway and the better version costs them nothing extra.

The exception is when the old approach is causing the client trouble. If an editor is routinely doing something awkward because of how we modelled it two years ago, and a release makes that unnecessary, we'll quote the change and explain why. That's a fix, and we treat it as one.

Better isn't enough. It has to be better enough to justify re-teaching somebody their own job.

Wait one version: anything that touches the editor experience

Control panel changes ship well, and they ship into the middle of somebody's Tuesday. A client who has learned where a button is doesn't want a better button. They want the button where it was, so they can publish the thing they came to publish and get back to work.

So we let a version settle. We watch what the Craft community reports in the first few weeks, because the issues that matter tend to come from people running unusual setups rather than from the release notes. Then we move sites over in batches, and we tell the editors before we do it.

Waiting a few weeks costs close to nothing. Being the client who finds a regression costs a phone call, an apology, and a dent in the belief that we know what we're doing.

Skip entirely: anything that only benefits us

There's always something in a release that would make our development a bit more pleasant and make no visible difference to the studio or the client paying for it.

These are the easiest changes to justify internally and the hardest to defend to anyone else. A developer-experience improvement is real and it does eventually show up as speed, but that eventually is a long way off, and in the meantime somebody is paying for a change they'll never see.

We skip them on existing sites and adopt them on new ones, where they cost nothing.

The exception that overrides all of the above

Security. If a release fixes something exploitable, it goes out immediately across every site we host, same day where the severity warrants it, regardless of what else is happening.

This is the specific reason Craft and plugin updates within your major version are included in hosting rather than billed as amends. If patching needs an approval, someone has to be available and decide it's worth the money this month, which means it gets deferred, then skipped, then forgotten. Including it removes the decision.

Major versions are projects, not patches

Everything above is about point releases within a major version. Major version upgrades are a different job and we treat them as one: quoted, planned, scheduled, tested on a copy first.

Templates change. Plugins need compatible versions, and occasionally one hasn't shipped yet, which turns a two-day job into a decision about whether to replace a dependency. There's a deployment window, and someone available afterwards in case something shows up that testing didn't catch.

Pricing that as routine maintenance would mean either doing it badly or not doing it and not saying. Both are worse for a client than a proper quote and a date in the calendar.

What this looks like from the outside

If you're a studio we build for, almost none of this should reach you. Sites stay patched and nothing changes under your client without warning. Occasionally we'll mention that a new build will do something slightly differently, and that's usually all.

The net effect is that our sites run a little behind the newest available thing and a long way ahead of the average. Given how many sites are two major versions behind because upgrading was never anyone's job, we're comfortable with that.