Update README.md and MIGRATION-GUIDE.md files

CHANGES.txt

@@ -7,7 +7,7 @@
  - BREAKING CHANGES:
       - Updated the default value of the `updateOnSdkUpdate` and `updateOnSdkTimedout` parameters of the `useSplitClient` and `useSplitTreatments` hooks options object to `true`, to re-render on all SDK events by default. The same applies for the equivalent props in the `[with]SplitClient` and `[with]SplitTreatments` components.
       - Updated error handling: using the library modules without wrapping them in a `SplitFactoryProvider` component will now throw an error instead of logging it, as the modules requires the `SplitContext` to work properly.
-      - Updated the `SplitFactoryProvider` component to not accept a child as a function (render prop), to avoid unnecessary re-renders when using the library hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate the child as a function to a regular component.
+      - Updated the `SplitFactoryProvider` component to not accept a child as a function (render prop), to avoid unnecessary re-renders when using the library hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate your component to be passed as a regular React JSX element if you were using this pattern.
       - Removed the `core.trafficType` option from the SDK configuration object, and the `trafficType` parameter from the SDK `client()` method, `useSplitClient`, `useTrack`, `withSplitClient` and `SplitClient` component. This is because traffic types can no longer be bound to SDK clients in JavaScript SDK v11.0.0, and so the traffic type must be provided as first argument in the `track` method calls.
       - Removed deprecated modules: `SplitFactory` component, `useClient`, `useTreatments` and `useManager` hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate to the new alternatives.
       - Renamed `SplitSdk` to `SplitFactory` function, which is the underlying Split SDK factory, i.e., `import { SplitFactory } from '@splitsoftware/splitio'`.

MIGRATION-GUIDE.md

@@ -1,4 +1,261 @@
 
+# Migrating to React SDK v2.0.0
+
+React SDK v2.0.0 has a few breaking changes that you should consider when migrating from a previous version. The main changes are:
+
+- **Deprecated `useClient`, `useTreatments`, and `useManager` hooks have been removed.**
+
+Follow [this section](#migrating-to-get-react-sdk-v1100-improvements-replacing-the-deprecated-useclient-usetreatments-and-usemanager-hooks) to migrate to the new hooks `useSplitClient`, `useSplitTreatments`, and `useSplitManager` respectively.
+
+- **Deprecated `SplitFactory` provider has been removed, `withSplitFactory` is deprecated, and `SplitFactoryProvider` doesn't accept `updateOn` props and a render function as children anymore.**
+
+To migrate your existing code to the new version of `SplitFactoryProvider`, consider the following refactor example:
+
+```tsx
+const MyComponent = (props: ISplitContextValues) => {
+  const { factory, client, isReady, isReadyFromCache, ... } = props;
+  ...
+};
+
+// if using SplitFactoryProvider v1.11.0
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} updateOnSdkUpdate={false} attributes={DEFAULT_CLIENT_ATTRIBUTES} >
+      {MyComponent}
+    </SplitFactoryProvider>
+  );
+};
+
+// or SplitFactory
+const App = () => {
+  return (
+    <SplitFactory config={mySplitConfig} updateOnSdkUpdate={false} attributes={DEFAULT_CLIENT_ATTRIBUTES} >
+      {MyComponent}
+    </SplitFactory>
+  );
+};
+
+// or withSplitFactory
+const App = withSplitFactory(mySplitConfig, undefined, DEFAULT_CLIENT_ATTRIBUTES)(
+  MyComponent, false /* updateOnSdkUpdate = false */
+);
+```
+
+should be refactored to:
+
+```tsx
+const MyComponent = () => {
+  const props: ISplitContextValues = useSplitClient({ updateOnSdkUpdate: false });
+  const { factory, client, isReady, isReadyFromCache, ... } = props;
+  ...
+};
+
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} attributes={DEFAULT_CLIENT_ATTRIBUTES} >
+      <MyComponent />
+    </SplitFactoryProvider>
+  );
+};
+```
+
+Notice that `MyComponent` was refactored to use the `useSplitClient` hook and is passed as a React JSX element rather than a render function.
+The `useSplitClient` hook is called without providing an `splitKey` param, meaning that the default client, which key is set in the `core.key` property of the `mySplitConfig` object, will be used, and the `updateOn` and `attributes` props are passed as options to the hook.
+
+- **High-Order-Components (`withSplitClient`, `withSplitTreatments`) and components that accept a render function as child component (`SplitTreatments`, and `SplitClient`) have been deprecated and might be removed in a future major release.**
+
+The deprecation is intended to simplify the API and discourage using old patterns (HOCs and render props) in favor of the *hook* alternatives, to take advantage of React optimizations.
+
+To migrate your existing code based on `withSplitClient` or `SplitClient`, consider the following refactor using the `useSplitClient` hook:
+
+```tsx
+const MyComponent = (props: ISplitContextValues) => {
+  const { client, isReady, ... } = props;
+  ...
+};
+
+const App = withSplitFactory(mySplitConfig)(
+  withSplitClient(OTHER_KEY, OTHER_KEY_ATTRIBUTES)(
+    MyComponent, undefined, undefined, undefined, false /* updateOnSdkReadyFromCache = false */
+  )
+);
+
+// or
+const App = () => {
+  return (
+    <SplitFactory config={mySplitConfig} >
+      <SplitClient splitKey={OTHER_KEY} attributes={OTHER_KEY_ATTRIBUTES} updateOnSdkReadyFromCache={false} >
+        {MyComponent}
+      </SplitClient>
+    </SplitFactory>
+  )
+};
+```
+
+should be refactored to:
+
+```tsx
+const MyComponent = () => {
+  const props: ISplitContextValues = useSplitClient({ splitKey: OTHER_KEY, attributes: OTHER_KEY_ATTRIBUTES, updateOnSdkReadyFromCache: false });
+  const { client, isReady, ... } = props;
+  ...
+};
+
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} >
+      <MyComponent />
+    </SplitFactory>
+  )
+};
+```
+
+To migrate your existing code based on `withSplitTreatments` or `SplitTreatments`, consider the following refactor using the `useSplitTreatments` hook:
+
+```tsx
+const MyComponent = (props: ISplitTreatmentsChildProps) => {
+  const { treatments, isReady, ... } = props;
+  ...
+};
+
+const App = withSplitFactory(mySplitConfig)(
+  withSplitClient(OTHER_KEY)(
+    withSplitTreatments(FEATURE_FLAG_NAMES, ATTRIBUTES)(
+      MyComponent
+    )
+  )
+);
+
+// or
+const App = () => {
+  return (
+    <SplitFactory config={mySplitConfig} >
+      <SplitClient splitKey={OTHER_KEY} >
+        <SplitTreatments names={FEATURE_FLAG_NAMES} attributes={ATTRIBUTES} >
+          {MyComponent}
+        </SplitTreatments>
+      </SplitClient>
+    </SplitFactory>
+  )
+};
+```
+
+should be refactored to:
+
+```tsx
+const MyComponent = () => {
+  const props: ISplitTreatmentsChildProps = useSplitTreatments({ splitKey: OTHER_KEY, names: FEATURE_FLAG_NAMES, attributes: ATTRIBUTES });
+  const { treatments, isReady, ... } = props;
+  ...
+};
+
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} >
+      <MyComponent />
+    </SplitFactory>
+  )
+};
+```
+
+- **Renamed `SplitSdk` function to `SplitFactory`.**
+
+If you are using the `SplitSdk` function to create a factory and pass it to the `SplitFactoryProvider` component, you should rename it to `SplitFactory`. For example:
+
+```tsx
+import { SplitSdk, SplitFactoryProvider } from '@splitsoftware/splitio-react';
+
+const myFactory = SplitSdk(mySplitConfig);
+
+const App = () => {
+  return (
+    <SplitFactoryProvider factory={myFactory} >
+      <MyComponent />
+    </SplitFactoryProvider>
+  );
+};
+```
+
+should be refactored to:
+
+```tsx
+import { SplitFactory, SplitFactoryProvider } from '@splitsoftware/splitio-react';
+
+const myFactory = SplitFactory(mySplitConfig);
+
+const App = () => {
+  return (
+    <SplitFactoryProvider factory={myFactory} >
+      <MyComponent />
+    </SplitFactoryProvider>
+  );
+};
+```
+
+- **Traffic type cannot be bound to SDK clients anymore.**
+
+If you were passing the `trafficType` to the SDK config or the `useSplitClient` or `useTrack` hooks, you should remove it. The `trafficType` is now required to be passed as initial argument of the `track` method. For example:
+
+```tsx
+const mySplitConfig = {
+  core: {
+    authorizationKey: YOUR_CLIENT_SIDE_SDK_KEY,
+    key: USER_KEY,
+    trafficType: 'user'
+  }
+}
+
+const MyComponent = () => {
+  const track = useTrack();
+  const accountTrack = useTrack(ACCOUNT_KEY, 'account');
+
+  useEffect(() => {
+    track('my_event');
+    accountTrack('my_event');
+  }, []);
+
+  ...
+};
+
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} >
+      <MyComponent />
+    </SplitFactory>
+  )
+};
+```
+
+should be refactored to:
+
+```tsx
+const mySplitConfig = {
+  core: {
+    authorizationKey: YOUR_CLIENT_SIDE_SDK_KEY,
+    key: USER_KEY
+  }
+}
+
+const MyComponent = () => {
+  const track = useTrack();
+  const accountTrack = useTrack(ACCOUNT_KEY);
+
+  useEffect(() => {
+    track('user', 'my_event');
+    accountTrack('account', 'my_event');
+  }, []);
+  ...
+};
+
+const App = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig} >
+      <MyComponent />
+    </SplitFactory>
+  )
+};
+```
+
 # Migrating to get React SDK v1.11.0 improvements: Replacing the deprecated `SplitFactory` and `withSplitFactory` components
 
 Starting from React SDK v1.11.0, the `SplitFactoryProvider` component is available and can replace the older `SplitFactory` and `withSplitFactory` components. The deprecated components will continue working, until they are removed in a future major release.

README.md

@@ -9,9 +9,7 @@ This SDK is designed to work with Split, the platform for controlled rollouts, w
 
 ## Compatibility
 
-This SDK is compatible with React 16.3.0 and above, since it uses [React Context API](https://reactjs.org/docs/context.html).
-
-Some features, such as `useSplitClient` and `useSplitTreatments`, use [React Hooks API](https://reactjs.org/docs/hooks-overview.html) that requires React 16.8.0 or later.
+This SDK is compatible with React 16.8.0 and above, since it uses **React Hooks API** introduced in that version.
 
 ## Getting started
 Below is a simple example that describes the instantiation and most basic usage of our SDK: