docs: add v20 migration guide (#4859)

Closes #4842

Author: timdeschryver

projects/ngrx.io/content/guide/migration/v20.md

@@ -7,7 +7,11 @@ NgRx supports using the Angular CLI `ng update` command to update your dependenc
 To update your packages to the latest released version, run the command below.
 
 ```sh
-ng update @ngrx/store@20
+# NgRx Store related packages
+ng update @ngrx/[email protected]
+
+# NgRx Signals package
+ng update @ngrx/[email protected]
 ```
 
 ## Dependencies
@@ -20,3 +24,207 @@ Version 20 has the minimum version requirements:
 - RxJS version ^6.5.x || ^7.5.0
 
 ## Breaking changes
+
+### Signals
+
+The internal `STATE_SOURCE` is no longer represented as a single `WritableSignal` holding the entire state object. Instead, each top-level state property becomes its own `WritableSignal` or remains as-is if a `WritableSignal` is provided as a state property.
+
+BEFORE:
+
+1. The initial state object reference is preserved:
+
+```ts
+const initialState = { ngrx: 'rocks' };
+
+// signalState:
+const state = signalState(initialState);
+state() === initialState; // true
+
+// withState:
+const Store = signalStore(withState(initialState));
+const store = new Store();
+getState(store) === initialState; // true
+```
+
+2. Top-level `WritableSignal`s are wrapped with `Signal`s:
+
+```ts
+// signalState:
+const state = signalState({ ngrx: signal('rocks') });
+state.ngrx // type: Signal<WritableSignal<string>>
+
+// withState:
+const Store = signalStore(withState({ ngrx: signal('rocks') }));
+const store = new Store();
+store.ngrx // type: Signal<WritableSignal<string>>
+```
+
+3. Root state properties can be added dynamically:
+
+```ts
+// signalState:
+const state = signalState<Record<string, string>>({});
+console.log(state()); // {}
+
+patchState(state, { ngrx: 'rocks' });
+console.log(state()); // { ngrx: 'rocks' }
+
+// withState:
+const Store = signalStore(
+  { protectedState: false },
+  withState<Record<string, string>>({})
+);
+const store = new Store();
+console.log(getState(store)); // {}
+
+patchState(store, { ngrx: 'rocks' });
+console.log(getState(store)); // { ngrx: 'rocks' }
+```
+
+AFTER:
+
+1. The initial state object reference is not preserved:
+
+```ts
+const initialState = { ngrx: 'rocks' };
+
+// signalState:
+const state = signalState(initialState);
+state() === initialState; // false
+
+// withState:
+const Store = signalStore(withState(initialState));
+const store = new Store();
+getState(store) === initialState; // false
+```
+
+2. Top-level `WritableSignal`s are not wrapped with `Signal`s:
+
+```ts
+// signalState:
+const state = signalState({ ngrx: signal('rocks') });
+state.ngrx // type: Signal<string>
+
+// withState:
+const Store = signalStore(withState({ ngrx: signal('rocks') }));
+const store = new Store();
+store.ngrx // type: Signal<string>
+```
+
+3. Root state properties can not be added dynamically:
+
+```ts
+// signalState:
+const state = signalState<Record<string, string>>({});
+console.log(state()); // {}
+
+patchState(state, { ngrx: 'rocks' });
+console.log(state()); // {}
+
+// withState:
+const Store = signalStore(
+  { protectedState: false },
+  withState<Record<string, string>>({})
+);
+const store = new Store();
+console.log(getState(store)); // {}
+
+patchState(store, { ngrx: 'rocks' });
+console.log(getState(store)); // {}
+```
+
+### Entity
+
+#### `getInitialState` is type-safe
+
+`getInitialState` is now type-safe, meaning that the initial state must match the entity state type. This change ensures that the initial state is correctly typed and prevents additional properties from being added to the state.
+
+BEFORE:
+
+```ts
+import { EntityState, createEntityAdapter, EntityAdapter } from '@ngrx/entity';
+
+interface Book {
+  id: string;
+  title: string;
+}
+interface BookState extends EntityState<Book> {
+  selectedBookId: string | null;
+}
+
+export const adapter: EntityAdapter<Book> = createEntityAdapter<Book>();
+export const initialState: BookState = adapter.getInitialState({
+  selectedBookId: '1',
+  otherProperty: 'value',
+});
+```
+
+AFTER:
+
+```ts
+
+import { EntityState, createEntityAdapter, EntityAdapter } from '@ngrx/entity';
+
+interface Book {
+  id: string;
+  title: string;
+}
+interface BookState extends EntityState<Book> {
+  selectedBookId: string | null;
+}
+
+export const adapter: EntityAdapter<Book> = createEntityAdapter<Book>();
+export const initialState: BookState = adapter.getInitialState({
+  selectedBookId: '1',
+  // 👇 this throws an error
+  // otherProperty: 'value',
+});
+```
+
+### Effects
+
+#### `act` operator is removed
+
+The `act` operator is removed in favor of core RxJS flattening operators and `mapResponse` from the `@ngrx/operators` package.
+
+BEFORE:
+
+```ts
+@Injectable()
+export class AuthEffects {
+  readonly login$ = createEffect(() => {
+    return this.actions$.pipe(
+      ofType(LoginPageActions.loginFormSubmitted),
+      act({
+        project: ({ credentials }) =>
+          this.authService
+            .login(credentials)
+            .pipe(map((user) => AuthApiActions.loginSuccess({ user }))),
+        error: (error) => AuthApiActions.loginFailure({ error }),
+        operator: exhaustMap,
+      })
+    );
+  });
+}
+```
+
+AFTER:
+
+```ts
+@Injectable()
+export class AuthEffects {
+  readonly login$ = createEffect(() => {
+    return this.actions$.pipe(
+      ofType(LoginPageActions.loginFormSubmitted),
+      exhaustMap(({ credentials }) =>
+        this.authService.login(credentials).pipe(
+          mapResponse({
+            next: (user) => AuthApiActions.loginSuccess({ user }),
+            error: (error) => AuthApiActions.loginFailure({ error }),
+          })
+        )
+      )
+    );
+  });
+}
+```