Skip to content

docs(changelog): mark the v0.3.0 replay-default and session-API changes as breaking - #46

Merged
Fiona2016 merged 1 commit into
publishfrom
docs/v0.3.0-breaking-notes
Sep 28, 2026
Merged

Fiona2016 merged 1 commit into
publishfrom
docs/v0.3.0-breaking-notes

Conversation

@flashduty

@flashduty flashduty Bot commented Sep 21, 2026 •

Copy link
Copy Markdown

Why

Two of the changes in the v0.3.0 section alter the behaviour or the types an existing installation
already depends on, and neither carries the 💥 marker that this file's legend (CHANGELOG.md:5) defines
for a breaking change. The convention already exists in this file: v0.2.0 has a 💥 **Breaking** line
for a removed init option and a 💥 **Breaking for TypeScript code that implements our interfaces** line
for interface members gaining members.

What this PR changes

Documentation only — CHANGELOG.md, no source file.

  1. startSessionReplayRecordingManually default flip. configuration.ts:482-488 now defaults it to
    false whenever remoteConfigurationEnabled is set, where it used to default to
    sessionReplaySampleRate === 0. An existing site with remote configuration on and an init replay rate
    of 0 — that is, a site that never passed the new options — starts recording on its own, and a console
    delivered rate now uploads and bills replays it previously only stored. The site has to change nothing
    to get that. It is currently logged as 🐛 alone, so a reader scanning for the breaking marker misses it.

  2. SessionManager.updateSessionState changed shape. In @flashcatcloud/browser-core, v0.2.3
    packages/core/src/domain/session/sessionManager.ts:23 was
    (state: Partial<SessionState>) => void; v0.3.0 is
    (update: (state: SessionState) => Partial<SessionState> | undefined) => void. SessionManager and
    SessionState are both exported from that package's entry point (packages/core/src/index.ts:61,
    :133), so a consumer calling updateSessionState({ ... }) compiles under v0.2.x and throws
    update is not a function at runtime under v0.3.0.

    Blast radius is small: every in-repo caller was migrated (packages/rum-core/src/domain/rumSessionManager.ts:427,
    :448, :519), and the entry points a page bundle actually uses are unaffected. It is only the
    published @flashcatcloud/browser-core surface that moved.

Alternative to (2)

The change could instead be made backward-compatible rather than documented as breaking:

updateSessionState: (update: ((state: SessionState) => Partial<SessionState> | undefined) | Partial<SessionState>) => void

with sessionStore.ts:224-229 narrowing on typeof update === 'function'. The function form exists so a
write that waited on the store lock can check it still targets the same session (state.id === ...) and
become a no-op otherwise; the object form cannot express that check, so keeping it would keep that race
open for any external caller. This PR documents the change as breaking instead.

Verification

Docs only. CI's formatting check covers the added lines; they are ≤ 110 characters and markdown
proseWrap defaults to preserve, so no rewrapping is expected.

… breaking

The v0.3.0 entry describes two changes that alter existing installations
rather than only adding to them, and neither carries the 💥 marker the
legend defines for a breaking change:

- `startSessionReplayRecordingManually` now defaults to false whenever
  `remoteConfigurationEnabled` is on, so a site that gates recording on
  consent by calling `startSessionReplayRecording()` itself starts
  recording — and has replays uploaded and billed — without changing
  anything on its side. It is currently logged as 🐛 only.
- `SessionManager.updateSessionState`, exported from
  `@flashcatcloud/browser-core`, changed shape in this release: it takes
  an updater function where it used to take a `Partial<SessionState>`.
  That is the case v0.2.0 already covers with a 💥 line of its own
  ("Breaking for TypeScript code that implements our interfaces"), and
  this release does not mention it.

Docs only: no source file is touched.
@Fiona2016 Fiona2016 changed the title docs(changelog): mark the v0.3.0 behaviour and session-API changes as breaking (weekly review) docs(changelog): mark the v0.3.0 replay-default and session-API changes as breaking Sep 28, 2026
@Fiona2016
Fiona2016 merged commit e70cf09 into publish Sep 28, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant