Journal · 28 January 2026

The quiet cost of unversioned event names

An event name is a public contract. When a squad changes checkout_started to mean “payment sheet visible” after two years of it meaning “cart validated,” every historical chart becomes a collage. App Analytics tools will still draw a confident line. The line is now two products pretending to be one.

Teams rename in place because it looks tidy. The tracking plan stays short. The vendor’s autocomplete stays clean. The cost arrives later, usually during a board request for “retention before the redesign,” when nobody can split the stream without a forensic intern and a lucky git blame.

A version is not clutter

We teach a dull rule in Event Grammar: if the meaning changes, the name changes, and the old name is frozen. checkout_started.v2 is ugly. Ugliness is a feature. It announces that history exists. A property schema_version on a stable name can work if you are disciplined; most squads are not, which is why we prefer the suffix they cannot ignore.

Aliases belong in a dictionary, not in production. “Also known as purchaseBegin on iOS 14” is a footnote for humans. Shipping both names forever is how Android and iOS drift into separate dialects.

What to freeze, what to kill

Freeze when analysts still need the old meaning for a year of comparison. Kill when the event was experimental and the sample is small. Killing is a dated decision, written down, not a silent deletion from the plan. In Taxonomy Atelier we keep a kill-list with a reviewer and a date. Without that list, “deprecated” means “still firing in 11% of sessions.”

Warehouses make the problem feel optional. You can always patch a view. Views rot. The product still emits the wrong sentence. Fix the sentence.

A practical week

Export thirty days of event names. Highlight any that were renamed in the last year without a version. For each, write the old meaning, the new meaning, and the first app version that shipped the change. If you cannot find the version, you do not have analytics yet — you have folklore. Bring that table to the desk if you want it annotated; it is the most useful attachment we receive.