From d11ebec449758a36688a90f9793196011e95159d Mon Sep 17 00:00:00 2001 From: nerdchanii Date: Fri, 29 May 2026 05:30:25 +0900 Subject: [PATCH] docs: rewrite compatibility and migration for users --- docs/public/compatibility/index.md | 36 ++++++------------------------ docs/public/migration/index.md | 26 ++++++++++----------- 2 files changed, 19 insertions(+), 43 deletions(-) diff --git a/docs/public/compatibility/index.md b/docs/public/compatibility/index.md index 020f729..a4aaa66 100644 --- a/docs/public/compatibility/index.md +++ b/docs/public/compatibility/index.md @@ -21,20 +21,18 @@ share a protocol, but they do not own the same behavior. - schema-safe hook state and payload types - React subscription setup and cleanup through `useSyncExternalStore` -For the framework-agnostic store contract, use the -[`socket-store` README](https://github.com/nerdchanii/socket-store#readme) and -[`socket-store` API contract](https://github.com/nerdchanii/socket-store/blob/main/docs/guide/api.md) -instead of treating this React adapter page as the source of truth. This page -only documents which core package version the adapter is expected to consume -and which behavior remains adapter-owned. +For the framework-agnostic store behavior, use the +[`socket-store` docs](https://nerdchanii.github.io/socket-store/). This page +only documents supported package pairings and which behavior remains +adapter-owned. ## Compatibility Table | react-socket-store | socket-store | Status | Notes | | --- | --- | --- | --- | -| `0.0.5` | `^0.0.3` | Supported current pairing | The adapter imports only from public package roots and consumes the released core package boundary. | -| `0.0.4` | `^0.0.2` | Previous pairing | Supported for existing consumers that have not upgraded to the latest core package. | -| Future adapter release requiring new core behavior or public core types | Future npm `socket-store` release that contains that contract | Not supported until both packages are released | Do not publish or document a new adapter pairing until the required core version is available from npm and the migration notes name the minimum version. | +| `0.0.5` | `^0.0.3` | Supported current pairing | Current documented pairing. | +| `0.0.4` | `^0.0.2` | Older pairing | Upgrade when you want the latest public docs and compatibility guidance. | +| Future adapter release requiring new core behavior or public core types | Matching future `socket-store` npm release | Not supported yet | Wait for a documented pairing before upgrading both packages together. | Do not import from generated `socket-store/dist/*` paths. Use package root exports only. @@ -42,23 +40,3 @@ exports only. The table only lists supported npm pairings and explicit unreleased boundaries. It does not make local `socket-store` main-branch behavior available to published `react-socket-store` consumers. - -## Release Order - -Release `socket-store` first when adapter work depends on new core behavior, new -public core types, or a higher minimum core version. After the core package is -available on npm, update `react-socket-store` to consume that public contract -through package-root exports and release the adapter. - -Adapter-only docs, examples, hook tests, and React cleanup fixes can release -without a core release when they do not require a new core contract. - -No breaking migration is required for the current compatibility boundary. The -current stabilization docs preserve the package-root import boundary while -updating the pairing to `react-socket-store@0.0.5` and `socket-store@^0.0.3`. - -If a future adapter release requires a newer core contract, document the -minimum `socket-store` version, dependency range change, import changes, and -React-visible hook or provider changes before publishing. - -Maintainer release gates are intentionally kept outside the published docs. diff --git a/docs/public/migration/index.md b/docs/public/migration/index.md index 3dc94be..c1e09e8 100644 --- a/docs/public/migration/index.md +++ b/docs/public/migration/index.md @@ -1,7 +1,14 @@ # Migration -No breaking migration is required for the current stabilization docs. Existing -consumers on `react-socket-store@0.0.4` should keep using `socket-store@^0.0.2`. +No breaking migration is required for the current documented pairing. + +If you are upgrading to the latest public docs baseline, use: + +- `react-socket-store@0.0.5` +- `socket-store@^0.0.3` + +Existing consumers on `react-socket-store@0.0.4` can stay on +`socket-store@^0.0.2` until they are ready to move both packages together. Use public package entrypoints when moving code onto the stabilized adapter: @@ -20,12 +27,7 @@ Keep React adapter docs focused on provider setup, hook behavior, render timing, subscription cleanup, and schema-safe hook usage. Link to `socket-store` for core WebSocket topic-store behavior. -Before publishing an adapter release that raises the required `socket-store` -contract, add migration notes that name the minimum compatible `socket-store` -version, dependency range changes, import changes, React hook or provider -behavior changes, and any removed or deferred support. - -## Current Stabilization Notes +## Current Notes The current docs clarify existing package boundaries rather than changing the runtime contract: @@ -36,13 +38,9 @@ runtime contract: - `react-socket-store` remains responsible for React context wiring, store-direct hooks, schema-safe hook types, and subscription cleanup through `useSyncExternalStore`. -- The adapter still depends on `socket-store@^0.0.2`. +- The latest adapter pairing uses `socket-store@^0.0.3`. - Local adapter contract types remain in `react-socket-store` until a future `socket-store` npm release exposes the stronger adapter-facing type surface. -When a future release raises the minimum `socket-store` version, update this -page before publishing with the exact npm version, dependency range, and any -consumer code changes. - See [Compatibility](../compatibility/) for the package responsibility split, -current version pairing, and cross-package release order. +current version pairing, and supported package combinations.