Update recommendations for reset

Author: satya164

versioned_docs/version-6.x/navigation-actions.md

@@ -81,8 +81,9 @@ If you want to preserve the existing screens but only want to modify the state,
 import { CommonActions } from '@react-navigation/native';
 
 navigation.dispatch(state => {
-  // Remove the home route from the stack
-  const routes = state.routes.filter(r => r.name !== 'Home');
+  // Remove all the screens after `Profile`
+  const index = state.routes.findIndex(r => r.name === 'Profile');
+  const routes = state.routes.slice(0, index + 1);
 
   return CommonActions.reset({
     ...state,
@@ -98,6 +99,15 @@ Consider the navigator's state object to be internal and subject to change in a
 
 :::
 
+#### Rewriting the history with `reset`
+
+Since the `reset` action can update the navigation state with a new state object, it can be used to rewrite the navigation history. However, rewriting the history to alter the back stack is not recommended in most cases:
+
+- It can lead to a confusing user experience, as users expect to be able to go back to the screen they were on before.
+- When supporting the Web platform, the browser's history will still reflect the old navigation state, so users will see the old screen if they use the browser's back button - resulting in 2 different experiences depending on which back button the user presses.
+
+So if you have such a use case, consider a different approach - e.g. updating the history once the user navigates back to the screen that has changed.
+
 ### goBack
 
 The `goBack` action creator allows to go back to the previous route in history. It doesn't take any arguments.

versioned_docs/version-7.x/navigation-actions.md

@@ -87,8 +87,9 @@ If you want to preserve the existing screens but only want to modify the state,
 import { CommonActions } from '@react-navigation/native';
 
 navigation.dispatch(state => {
-  // Remove the home route from the stack
-  const routes = state.routes.filter(r => r.name !== 'Home');
+  // Remove all the screens after `Profile`
+  const index = state.routes.findIndex(r => r.name === 'Profile');
+  const routes = state.routes.slice(0, index + 1);
 
   return CommonActions.reset({
     ...state,
@@ -104,6 +105,15 @@ Consider the navigator's state object to be internal and subject to change in a
 
 :::
 
+#### Rewriting the history with `reset`
+
+Since the `reset` action can update the navigation state with a new state object, it can be used to rewrite the navigation history. However, rewriting the history to alter the back stack is not recommended in most cases:
+
+- It can lead to a confusing user experience, as users expect to be able to go back to the screen they were on before.
+- When supporting the Web platform, the browser's history will still reflect the old navigation state, so users will see the old screen if they use the browser's back button - resulting in 2 different experiences depending on which back button the user presses.
+
+So if you have such a use case, consider a different approach - e.g. updating the history once the user navigates back to the screen that has changed.
+
 ### goBack
 
 The `goBack` action creator allows to go back to the previous route in history. It doesn't take any arguments.