Skip to content

docs(ai-migration): make the v9 → v10 guide agent-ready and re-verify against V10 - #3918

Merged
oliverlaz merged 2 commits into
V10from
docs/v10-agent-migration-guide
Nov 3, 2026
Merged

docs(ai-migration): make the v9 → v10 guide agent-ready and re-verify against V10#3918
oliverlaz merged 2 commits into
V10from
docs/v10-agent-migration-guide

Conversation

@oliverlaz

@oliverlaz oliverlaz commented Nov 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Ticket: https://linear.app/stream/issue/REACT-1307

Goal

Make the v9 → v10 guide the input of a prebuilt migration prompt: a coding agent gets one URL plus the user's repo and has to migrate accurately. The guide had grown by accretion, which hurt that:

  • "Part I" and "§19" each appeared twice;
  • Verify sat in the middle of the guide;
  • K.8 came before K.6;
  • detection greps hard-coded src/;
  • there was history from release candidates, and many bug-fix sections with nothing for an integrator to do.

Changes

ai-docs/ai-migration-v9-to-v10.md: structure

  • The order is now:
    1. Title and verified line
    2. Rules (old §0 folded in)
    3. Companion documents
    4. Workflow, definition of done and report template
    5. Detection (rg -t js -t ts -g '!**/node_modules/**', keyed on v9 names)
    6. Quick reference (20 rows added)
    7. A consolidated "Breaks that compile" table (~40 rows, each with a Detect command)
    8. Parts A–S
    9. Verification, with a leftover-identifier grep
    10. An index mapping every v10-breaking-changes.md section to a guide section
  • IDs:
    • Verify is now an unnumbered ## Verification, so every existing §19 reference (all of them mean i18n) stays valid.
    • The duplicate Part I (i18n) is now Part S.
    • K.x sections are in order.
    • Every § reference in ai-docs/ resolves to a unique heading.
  • Sections with no integrator action are one-liners: L.8–L.10, M.1, M.3–M.5, M.7, P.10, P.14, P.16, P.18, P.19, P.21, P.22, Q.2. Their full text moved to section 17 of v10-breaking-changes.md.

Accuracy, re-verified at 74884ff55

  • fix: v10 sdk regressions #3916: a channel or thread reopened on an older page now jumps to the latest messages, and useJumpToLatestOnOpen is exported. Covered in §8, §R.5, the breaks table and the reference.
  • Wrong claim fixed: <Chat> does not replace an app's statusReporter; the app's reporter wins (§R.2).
  • Other fixes:
    • §16.3: capability gating;
    • useMutedUsers() returns UserMuteResponse[];
    • the typing type;
    • deleted_by is removed;
    • DEFAULT_BACKEND_SORT is not exported;
    • a dead stream-chat-js link.
  • Names that only existed in release candidates are removed. Checked against the v9.11.1 / stream-chat 9.54.4 tags:
    • the channel.state.*Store handles and mutedUsersStore;
    • WatcherState, which was in §4's After snippet;
    • MutedUsersState, normalizeTimestamp, getChannelUnreadState and *WithLocalUpdate.
  • Remaining stale mentions fixed: channel.deactivate() and client.activeChannels in channel-state-ui-migration.md, and the markRead description in v10-docs-impact.md.
  • ai-migration.md (v8 → v9) has a banner pointing to this guide.

How it was checked

  • Every identifier in the guide was checked against the SDK source, stream-chat-js src/ and @stream-io/i18n / state-store. All 1,292 root exports were listed with the TS compiler, and every recommended hook is a root export.
  • About 40 v10 snippets typecheck against package/src.
  • The detection, breaks-table and leftover greps were run on the v9 and v10 SampleApps.

Needs a decision

  • Deep link vs reopen-at-latest. If an app starts jumpToMessage in a screen-level useLayoutEffect, the SDK's jump to the latest messages may fire first. The SDK tests only cover a jump started before <Channel> mounts, so the guide recommends that order. Worth a test or a guard in the hook.
  • Phase 1 asks which pre-release to use when no stable 10.x exists. Check that this fits the prebuilt prompt during the RC period.

Notes

  • The raw link to the stream-chat-js guide resolves once its PR is merged into release-v10.
  • The local package/node_modules/stream-chat is rc.26; yarn install brings it to rc.30.

Related PRs

The three guides link to each other; review together:

@oliverlaz
docs(ai-migration): make the v9 → v10 guide agent-ready and re-verify…
8319280 
… against V10

Restructure ai-docs/ai-migration-v9-to-v10.md for coding agents: rules,
companion documents, a phased workflow with a definition of done and a
report template, root-agnostic detection, a consolidated table of breaks
that still compile, and verification with a leftover-identifier grep at
the end. Duplicate ids are resolved (i18n is Part S, Verify is unnumbered),
K.x is in order, and every § reference resolves.

Re-verify against V10 HEAD: cover #3916's reopen-at-latest default and
useJumpToLatestOnOpen, correct the statusReporter, useMutedUsers, typing
and DEFAULT_BACKEND_SORT claims, and drop names that only existed in
release candidates. Sections with no integrator action shrink to one line,
with their detail moved to v10-breaking-changes.md. The v8 → v9 guide now
points at this one.
This was referenced Nov 3, 2026
Merged
Open
@oliverlaz
oliverlaz requested a review from isekovanic November 3, 2026 09:46
@oliverlaz
docs(ai-migration): fix the moderation.flagMessage call shape
cf3a47a 
client.moderation.flagMessage and flagUser take an object
({ message_id } / { user_id }), not a positional id.
@oliverlaz
oliverlaz merged commit de21c4a into V10 Nov 3, 2026
6 checks passed
@oliverlaz
oliverlaz deleted the docs/v10-agent-migration-guide branch November 3, 2026 11:09
oliverlaz added a commit to GetStream/stream-chat-js that referenced this pull request Nov 3, 2026
@oliverlaz
docs(ai-docs): add the v9 → v10 agent migration guide and re-verify b…
c07b76d 
…reaking changes at HEAD (#1984)

Ticket: https://linear.app/stream/issue/REACT-1307

## Goal

Make the v9 → v10 migration docs usable as the input of a prebuilt
migration prompt: a coding agent gets one URL plus the user's repo, and
has to migrate accurately. Until now `stream-chat` had only the
exhaustive audit (`v10-breaking-changes.md`), and no execution guide.

## Changes

**New `ai-docs/ai-migration-v9-to-v10.md`** (entry guide, ~1.2k lines)
- Rules for the agent: the installed `node_modules/stream-chat` is the
source of truth, verify before writing, stop on a missing symbol,
smallest edit, a green build is not done.
- Companion documents, a phased workflow (preflight → install → detect →
apply → silent breaks → verify → report), a definition of done and a
report template.
- Detection greps keyed on v9 names that search the whole repo, not just
`src/`.
- A quick reference of about 125 v9 → v10 rows, each linked to a
reference anchor.
- Inline before/after snippets for the high-impact changes. All 25 v10
snippets compile with `tsc --strict` against `src/`.
- Breaks that compile, each with a Detect command.
- A leftover-identifier grep covering removed methods and events and all
376 removed type names.
- An index that maps all 243 reference anchors to guide sections or
"reference only".
- Server-side code (secret, token signing, webhooks, admin endpoints) is
detected and routed to `@stream-io/node-sdk`, not ported onto
`stream-chat`.

**`ai-docs/v10-breaking-changes.md`, re-verified at `fdfcb296` (rc.30)**
- New break: the #1969 regen dropped `call_level` from
`PushPreferenceInput` / `PushPreferencesResponse`. It also re-exported
`BlocklistBehavior` and `ModerationAction`, which the rename table
listed as removed.
- Read events after #1981:
- The `read-events` capability is checked via
`channel.readEventsEnabled`.
  - The reporter path resolves `null` instead of throwing.
  - Only a direct `markRead()` / `markUnread()` throws.
- Other entries updated to HEAD behaviour:
  - mark-read throttling is per channel/thread;
  - recovery re-queries loaded pages;
  - network-failed messages get `status: 0`;
  - thread participants are merged;
  - joined/invite filters and `addFilterResolvers`;
  - watcher, ban and member-removal events;
  - `user.updated` reaches threads;
  - the composer restores `custom` from drafts and edits.
- **No anchor renamed or removed.** The React and RN guides link to
them. One anchor was added: `composer-custom-data-restore`.

## How it was checked
- Every identifier on the "after" side was checked mechanically to exist
in `src/`; the only misses are v9 names, placeholders and prose.
- The detection and verification greps were run against a v9 fixture
app.
- `prettier --check` passes.

## Open questions for review
- For channels, should `updatePartial` set custom fields as
`'custom.name'` dot paths or as flat keys? React's
`ChannelManagementView` uses dot paths, while the docs-snippet test uses
flat keys.
- The reference still has a few notes for rc users (`ensureWatched`,
renamed paginator members). The guide has none. Keep them or drop them?


## Related PRs

The three guides link to each other; review together:
- stream-chat-js: #1984
(merge first: the React and RN guides link to its raw URL)
- stream-chat-react:
GetStream/stream-chat-react#3377
- stream-chat-react-native:
GetStream/stream-chat-react-native#3918
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@isekovanic isekovanic isekovanic approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@oliverlaz @isekovanic