Feature Flag

For a long time, deploying and releasing meant the same thing. The moment code went to the server, everything inside it was visible to users, so a team could not push code until a feature was completely finished. A two-month project like a new editor meant two months of code piling up on a separate branch, and because everyone else kept editing the same files in the meantime, merge day produced a conflict list hundreds of lines long.

The other direction was blocked too. If a screen deployed on a Friday evening threw errors, the only way back was to deploy again. At Pagedeck, users stared at a broken screen for more than thirty minutes while Theo worked through the steps to restore the previous version. The gap between noticing a problem and actually stopping it was always about that wide.

A feature flag solves both with the same move. Once "the code is on the server" and "the user can see this feature" become two separate facts, unfinished work can ship every day and a misbehaving feature can be stopped without a deploy.

You plant one branch in the code — if this flag is on, show the new screen, otherwise the old one — and decide the on-off state from outside the code. The flag value lives in a configuration store or a flag management tool rather than inside the build artifact, so changing it takes effect within seconds and needs no redeploy.

Three things follow from that structure.

1. Unfinished features can merge into the main line every day while switched off. Instead of merging two months of change at once, the team merges a day at a time, and conflicts get sliced that much smaller. A branch held for two months might touch forty files at merge time; merged daily, the same work arrives a few files at a time.
2. Responding to a problem means flipping a switch. What used to be a thirty-minute restore deploy becomes ten seconds.
3. You can choose who gets it. Turning a flag on only for internal accounts, or 1 percent of users, or paid plans lets you narrow the audience — which is why canary release, opening a change to a small group first, and percentage rollout, raising the exposure share in steps, both run on top of flags.

Flags divide into three kinds by what they were planted for. A release toggle hides work that isn't finished, so it gets removed once the feature is fully open. An experiment toggle splits the audience to compare which version performs better, so it disappears when the experiment ends. A permission toggle opens and closes features by plan or by role, so it stays for as long as the product lives. The first two are temporary scaffolding and the third is permanent fixture, and that difference decides how each one gets managed.

Three approaches solve the same problem without flags, and each gives up something different.

1. Keep a long-lived branch. Work on a separate branch until the feature is done, then merge. It costs nothing to adopt, but merge-day conflicts remain exactly as they were, and until the merge nobody knows whether the work runs correctly alongside everyone else's changes.
2. Separate the environments. Deploy to a staging server reachable only from inside the company. Real users and real data are missing there, so defects that only surface at scale, or errors that only occur with one customer's data, go unnoticed. A bug that appears only on accounts holding more than 2,000 documents will never show itself on a staging server holding twelve.
3. Respond with rollback. When something breaks, return the whole deployment to its previous version. It is decisive, but every healthy change riding in the same deployment gets reverted too, and you inherit the question of what to do with data already written in the new format.

What a flag costs is the branch left behind in the code. Two flags mean four on-off combinations, ten mean more than a thousand, and no team tests all of them. A team that plants five flags a quarter and removes none is carrying twenty by the end of the year. So in practice, the day a flag is planted, the date it will be removed gets written down with it.

"Put that behind a flag and ship it now. We can decide when to turn it on next week."

A proposal to schedule the code push and the feature launch separately.

"The error rate is spiking — I'm turning off the new editor flag first."

Stopping the impact before identifying the cause.

"This flag has been at 100 percent for three months and it's still in the code."

A temporary branch never got cleaned up, so it's time to remove it.

Pagedeck's new editor followed exactly that sequence. Theo planted a flag, left it off, and deployed every day for two weeks. Mia turned it on for internal accounts only and tried it first. With nothing wrong, they raised the share to 1 percent, then 10, then 25 — and at the 25 percent step, document saves started failing intermittently, so they switched it off on the spot. Two days later the fix went back out.

What the flag did here was not to bring a decision forward but to make it possible to postpone one. At the moment the code shipped, nobody had to know when it would open; at the moment it opened, the code had already been exercised.

The most common mistake is treating a flag as a licence to verify less, on the reasoning that anything wrong can just be switched off. But switching off stops future exposure only — whatever happened while the flag was on stays. If 300 documents were saved in a new format that the old screen can't open, taking the flag down leaves those 300 exactly as they are. Easy to turn off means exposure stops, not that recovery is easy.

Treating flags as fixtures that never need clearing is the other one. A flag already open to 100 percent looks harmless. But the branch that remains is a fork in the road for everyone who reads that code afterward, who has to work out whether this can still be turned off, and while the old path survives it has to keep being maintained too. In a codebase carrying dozens of flags, nobody can say how a new feature will behave under which combination, and the speed the flags were planted to buy gets handed back.