Announcing Behavior Changes

Announcing behavior changes

Some fixes correct wrong behavior but change what a user sees. The number moves, the chart shifts, the count drops. Nothing is broken, but from the user's side it is indistinguishable from a regression, and they have no way to find out why.

An in-app change notice closes that gap: it appears where the user sees the different result, says what changed, and then goes away.

The reference implementation is frontend/src/queries/nodes/DataVisualization/Components/SqlInsightDateFilterNotice.tsx, shipped in commit 76f2905222a alongside the backend change it explains. Read it before writing a new one — it is 60 lines and it is the whole pattern.

First: does this change need a notice?

Most changes do not. A notice that fires for people it does not concern is worse than no notice, because it teaches everyone to dismiss banners without reading them. Ship one only when all four hold.

1. A user who does nothing sees something different. Not a new feature, not a change they opted into behind a flag.
2. They cannot work out why from the screen. If the UI already explains it, the UI is the notice.
3. The difference is big enough to notice. A rounding change in the fourth decimal is not.
4. You can identify who is affected, in code. See below — this is the one that usually fails.

The narrowing test

Write the predicate first. If you cannot express "this user is affected" as a function of state the client already has, you are about to show a banner to everyone about something that concerns a minority.

When that happens, pick a different mechanism instead of widening the blast radius:

The pattern

Five pieces. All of them ship in the same PR as the behavior change, so a reviewer sees the change and its explanation together, and the notice cannot be forgotten once the change is out.

1. An exported, tested predicate

Mirror the backend rule in a named function, and say in a comment which backend code it mirrors so the two can be kept honest.

/** Whether the SQL date filter resolution fix can produce different results for this query.
 * Mirrors the affected shapes of ReplaceFilters in posthog/hogql/filters.py. */
export function isAffectedByDateFilterResolutionChange(source: HogQLQuery): boolean {

Export it separately from the component so it can be unit tested without rendering.

2. A feature flag

Declare it in frontend/src/lib/constants.tsx with an owner comment, in the same style as the neighbours:

SQL_INSIGHT_DATE_FILTER_NOTICE: 'sql-insight-date-filter-notice', // owner: #team-product-analytics, gates the notice on SQL insights affected by the date filter resolution fix

The flag does three jobs: it lets you roll the notice out gradually, it lets you turn it off without a deploy if the copy is wrong or the predicate is too broad, and it is the handle you retire the notice by when it has served its purpose.

3. A component that returns null by default

Both gates, flag first — it is the cheaper check and the kill switch:

export function SqlInsightDateFilterNotice({ source }: { source: HogQLQuery }): JSX.Element | null {
  const { featureFlags } = useValues(featureFlagLogic)

  if (!featureFlags[FEATURE_FLAGS.SQL_INSIGHT_DATE_FILTER_NOTICE] || !isAffectedByDateFilterResolutionChange(source)) {
    return null
  }

  return (
    <LemonBanner type="info" dismissKey="sql-insight-date-filter-notice">
      Date filters on SQL insights now match other insights: relative ranges start at midnight, and open-ended ranges
      include all of today but nothing after. Results may differ slightly from before.
    </LemonBanner>
  )
}

Use LemonBanner — do not hand-roll. type="info", because nothing is wrong. dismissKey gives permanent per-user dismissal through lemonBannerLogic's persist: true reducer, at no cost. Keep the key stable and equal to the flag key; changing it re-shows the notice to everyone who already dismissed it.

4. An anchor where the result appears

Render it next to the thing that looks different, not next to the control that changed. The exemplar sits above the visualization in DataVisualization.tsx, not on the date filter, because the chart is what the user is staring at.

Prefer one shared render site over many. A notice about relative date ranges placed in frontend/src/lib/components/DateFilter/DateFilter.tsx reaches insights, dashboards, web analytics, session replay, error tracking, and AI observability at once, because they all render that component.