Add info about re-entering child state nodes to the migration guide

Author: rlaffers

versioned_docs/version-5/migration.mdx

@@ -657,33 +657,31 @@ Breaking change
 
 :::
 
-All transitions are implicitly internal. This change is relevant for transitions defined on compound state nodes with `entry` or `exit` actions, invoked actors or delayed transitions (`after`). If you relied on implicit re-entering of a compound state node, use `reenter: true`:
+All transitions are implicitly internal. This change is relevant for transitions defined on compound state nodes with `entry` or `exit` actions, invoked actors, or delayed transitions (`after`). If you relied on implicit re-entering of a compound state node, use `reenter: true`:
 
 <Tabs>
 <TabItem value="v5" label="XState v5 beta">
 
 ```ts
 // ✅
-const machine = createMachine(
-  {
-    // ...
-    states: {
-      compoundState: {
-        entry: 'someAction',
-        on: {
-          someEvent: {
-            target: 'compoundState.childState',
-            reenter: true, // make it external explicitly!
-          },
-        },
-        initial: 'childState',
-        states: {
-          childState: {},
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      entry: 'someAction',
+      on: {
+        someEvent: {
+          target: 'compoundState.childState',
+          reenter: true, // make it external explicitly!
         },
       },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
     },
   },
-)
+})
 ```
 
 </TabItem>
@@ -692,26 +690,24 @@ const machine = createMachine(
 
 ```ts
 // ❌ DEPRECATED
-const machine = createMachine(
-  {
-    // ...
-    states: {
-      compoundState: {
-        entry: 'someAction',
-        on: {
-          someEvent: {
-            // implicitly external
-            target: 'compoundState.childState', // non-relative target
-          },
-        },
-        initial: 'childState',
-        states: {
-          childState: {},
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      entry: 'someAction',
+      on: {
+        someEvent: {
+          // implicitly external
+          target: 'compoundState.childState', // non-relative target
         },
       },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
     },
   },
-)
+})
 ```
 
 </TabItem>
@@ -722,25 +718,88 @@ const machine = createMachine(
 
 ```ts
 // ✅
-const machine = createMachine(
-  {
-    // ...
-    states: {
-      compoundState: {
-        after: {
-          1000: {
-            target: 'compoundState.childState',
-            reenter: true, // make it external explicitly!
-          }
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      after: {
+        1000: {
+          target: 'compoundState.childState',
+          reenter: true, // make it external explicitly!
+        }
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+
+<TabItem value="v4" label="XState v4">
+
+```ts
+// ❌ DEPRECATED
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      after: {
+        1000: {
+          // implicitly external
+          target: 'compoundState.childState', // non-relative target
+        }
+      },
+      initial: 'childState',
+      states: {
+        childState: {},
+      },
+    },
+  },
+})
+```
+
+</TabItem>
+</Tabs>
+
+### Child state nodes are always re-entered
+
+:::breakingchange
+
+Breaking change
+
+:::
+
+Child state nodes are always re-entered when they are targeted by transitions (both external and **internal**) defined on compound state nodes. This change is relevant only if a child state node has `entry` or `exit` actions, invoked actors, or delayed transitions (`after`). Add a `stateIn` guard to prevent undesirable re-entry of the child state:
+
+<Tabs>
+<TabItem value="v5" label="XState v5 beta">
+
+```ts
+// ✅
+
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      on: {
+        someEvent: {
+          guard: not(stateIn('compoundState.childState')),
+          target: '.childState',
         },
-        initial: 'childState',
-        states: {
-          childState: {},
+      },
+      initial: 'childState',
+      states: {
+        childState: {
+          entry: 'someAction',
         },
       },
     },
   },
-)
+})
 ```
 
 </TabItem>
@@ -749,30 +808,30 @@ const machine = createMachine(
 
 ```ts
 // ❌ DEPRECATED
-const machine = createMachine(
-  {
-    // ...
-    states: {
-      compoundState: {
-        after: {
-          1000: {
-            // implicitly external
-            target: 'compoundState.childState', // non-relative target
-          }
+
+const machine = createMachine({
+  // ...
+  states: {
+    compoundState: {
+      on: {
+        someEvent: {
+          target: '.childState', // implicitly internal, childState not re-entered
         },
-        initial: 'childState',
-        states: {
-          childState: {},
+      },
+      initial: 'childState',
+      states: {
+        childState: {
+          entry: 'someAction',
         },
       },
     },
   },
-)
+})
 ```
 
 </TabItem>
-</Tabs>
 
+</Tabs>
 
 ### Use `stateIn()` to validate state transitions, not `in`