03 Mar 2026
Migration without breaking dashboards
Renaming order_complete is easy in a repo. It is expensive in a board pack that still filters on the old string. Migration is therefore a product calendar, not only a data task.
Start with an alias map: old name, new name, surfaces still emitting the old one, dashboards that depend on it, owner of each dashboard. If you cannot list the dashboards, you are not ready to delete anything.
Dual-write both names for a window that product has seen. In Thailand we often use nine weeks so it covers a month-end and a quarterly review. Shorter windows please engineering and surprise finance.
During the window, new instrumentation uses only the new name plus the alias. Old code paths may still emit the legacy event. Analytics reports should read from a union or from the vendor’s alias feature if you trust it — and you should verify, not assume.
Deprecation is a date, not a feeling. After the window, the old name is rejected in code review. Saved reports that still break are the owner’s problem; that sentence belongs in the freeze note so it is not a surprise.
The Dashboard Migration Clinic is two days because the alias map is tedious and political. Someone’s favourite chart will use a misspelling. Write it down. Do not shame them in Slack; put the alias in the map.
If leadership wants a “big bang cutover,” show them the last quarter’s board screenshots. Most people become reasonable about nine weeks.