Repository: RasaHQ/rasa
Pull request: Update migration guide
**Proposed changes**:
- Fixes https://github.com/RasaHQ/rasa/issues/6863
- Documents https://github.com/RasaHQ/rasa/pull/6854

**Status (please check what you already did)**:
- [ ] added some tests for the functionality
- [x] updated the documentation
- [ ] updated the changelog (please check [changelog](https://github.com/RasaHQ/rasa/tree/master/changelog) for instructions)
- [ ] reformat files using `black` (please check [Readme](https://github.com/RasaHQ/rasa#code-style) for instructions)


Problem statement:
Update migration guide for migrating to rulepolicy
When collecitng user feedback about 2.0, users pointed out some missing information in the migration guide. We should address these comments: 

- [x] The migration guide doesn't tell users to remove old policy and replace with RulePolicy (e.g. when migrating from MappingPolicy to RulePolicy. 
- [x] A user missed to migrate config (RulePolicy was missing)
- [x] One user thought he was done before adding rulepolicy to his configuration
- [x] One user forgot to remove the mapping policy triggers: in the domain
- [ ] The migration before and after changes should have been explained with an example

Hints from issue discussion:

Commit message: give an example of what an updated domain looks like

Patch to review:
diff --git a/docs/docs/migration-guide.mdx b/docs/docs/migration-guide.mdx
index 9ae0a6fe258d..fd9296b19f28 100644
--- a/docs/docs/migration-guide.mdx
+++ b/docs/docs/migration-guide.mdx
@@ -57,13 +57,29 @@ deprecated:
 - [Two-Stage-Fallback Policy](./policies.mdx#two-stage-fallback-policy)
 - [Form Policy](./policies.mdx#form-policy)
 
-#### Migrating from the Mapping Policy
+:::tip Automatic migration
+Rasa Open Source can take care of automatically migrating the Mapping Policy,
+the Fallback Policy and the Two-Stage-Fallback Policy for you. To do so, run the
+following command:
+
+```bash
+rasa data convert config
+```
+
+This command will take care of updating your `config.yml`, `domain.yml` and `rules.yml`, while
+making backups of your pre-existing files using the `.bak` suffix.
+
+You can follow the steps below if you wish to do this migration manually.
+Please note that you would still need to [migrate the Form Policy](#migrating-from-the-form-policy) manually.
+:::
+
+#### Manually migrating from the Mapping Policy
 
 If you previously used the [Mapping Policy](./policies.mdx#mapping-policy), you
 can follow the documentation on [FAQs](./chitchat-faqs.mdx) to convert your mapped
 intents to rules. Suppose you previously mapped an intent `ask_is_bot` as follows:
 
-```yaml-rasa
+```yaml-rasa title="domain.yml"
 intents:
  - ask_is_bot:
      triggers: action_is_bot
@@ -71,7 +87,7 @@ intents:
 
 This becomes the following rule:
 
-```yaml-rasa
+```yaml-rasa title="rules.yml"
 rules:
 - rule: Rule to map `ask_is_bot` intent
   steps:
@@ -79,12 +95,28 @@ rules:
   - action: action_is_bot
 ```
 
-#### Migrating from the Fallback Policy
+And you can safely remove any trigger from your domain:
+
+```yaml-rasa title="domain.yml"
+intents:
+ - ask_is_bot
+```
+
+Finally, you can replace the Mapping Policy with the
+[Rule Policy](./policies.mdx#rule-policy) in your model configuration:
+
+```yaml-rasa title="config.yml"
+policies:
+  # Other policies
+  - name: RulePolicy
+```
+
+#### Manually migrating from the Fallback Policy
 
 If you previously used the [Fallback Policy](./policies.mdx#fallback-policy), the following model
 configuration would translate as follows given a previous configuration like this:
 
-```yaml-rasa
+```yaml-rasa title="config.yml"
 policies:
   - name: "FallbackPolicy"
     nlu_threshold: 0.4
@@ -95,12 +127,12 @@ policies:
 
 The new configuration would then look like:
 
-```yaml-rasa
+```yaml-rasa title="config.yml"
 policies:
-# Other policies
-- name: RulePolicy
-  core_fallback_threshold: 0.3
-  core_fallback_action_name: "action_default_fallback"
+  # Other policies
+  - name: RulePolicy
+    core_fallback_threshold: 0.3
+    core_fallback_action_name: "action_default_fallback"
 
 pipeline:
   # Other components
@@ -112,24 +144,24 @@ pipeline:
 In addition, you need to add a [Rule](./rules.mdx) to specify which action to run
 in case of low NLU confidence:
 
-```yaml-rasa
+```yaml-rasa title="rules.yml"
 rules:
-- rule: Ask the user to rephrase whenever they send a message with low NLU confidence
-  steps:
-  - intent: nlu_fallback
-  - action: utter_please_rephrase
+  - rule: Ask the user to rephrase whenever they send a message with low NLU confidence
+    steps:
+    - intent: nlu_fallback
+    - action: utter_please_rephrase
 ```
 
 Please see the [Fallbacks](./fallback-handoff.mdx#fallbacks) documentation for more
 information.
 
-#### Migrating from the Two-Stage-Fallback Policy
+#### Manually migrating from the Two-Stage-Fallback Policy
 
 If you previously used the
 [Two-Stage-Fallback Policy](./policies.mdx#two-stage-fallback-policy), the following model
 configuration would translate as follows given a previous configuration like this:
 
-```yaml-rasa
+```yaml-rasa title="config.yml"
 policies:
   - name: TwoStageFallbackPolicy
     nlu_threshold: 0.4
@@ -142,12 +174,12 @@ policies:
 
 The new configuration would then look like:
 
-```yaml-rasa
+```yaml-rasa title="config.yml"
 policies:
-# Other policies
-- name: RulePolicy
-  core_fallback_threshold: 0.3
-  core_fallback_action_name: "action_default_fallback"
+  # Other policies
+  - name: RulePolicy
+    core_fallback_threshold: 0.3
+    core_fallback_action_name: "action_default_fallback"
 
 pipeline:
   # Other components
@@ -159,16 +191,16 @@ pipeline:
 In addition you need to add a [Rule](./rules.mdx) to activate the Two-Stage Fallback for
 messages with low NLU confidence.
 
-```yaml-rasa
+```yaml-rasa title="rules.yml"
 rules:
-- rule: Implementation of the TwoStageFallbackPolicy
-  steps:
-  # This intent is automatically triggered by the `FallbackClassifier` in the NLU
-  # pipeline in case the intent confidence was below the specified threshold.
-  - intent: nlu_fallback
-  # The Fallback is now implemented as a form.
-  - action: action_two_stage_fallback
-  - active_loop: action_two_stage_fallback
+  - rule: Implementation of the TwoStageFallbackPolicy
+    steps:
+    # This intent is automatically triggered by the `FallbackClassifier` in the NLU
+    # pipeline in case the intent confidence was below the specified threshold.
+    - intent: nlu_fallback
+    # The Fallback is now implemented as a form.
+    - action: action_two_stage_fallback
+    - active_loop: action_two_stage_fallback
 ```
 
 Note that the previous parameters `fallback_nlu_action_name` and
@@ -178,7 +210,7 @@ Note that the previous parameters `fallback_nlu_action_name` and
 Please see the [Fallbacks](./fallback-handoff.mdx#fallbacks) documentation for more
 information.
 
-#### Form Policy
+#### Migrating from the Form Policy
 
 As of Rasa Open Source 2.0 the logic for [Forms](./forms.mdx) has been moved from the
 Rasa SDK to Rasa Open Source to simplify implementations of custom action libraries.
@@ -247,9 +279,9 @@ model configuration:
 
 ```yaml-rasa
 policies:
-# Other policies
-# ...
-- name: RulePolicy
+  # Other policies
+  # ...
+  - name: RulePolicy
 ```
 
 Then you need to define the form and the required slots in the domain as described in
@@ -270,17 +302,17 @@ form.
 
 ```yaml-rasa
 rules:
-- rule: Submit form
-  condition:
-  # Condition that form is active.
-  - active_loop: restaurant_form
-  steps:
-  - action: restaurant_form
-  - active_loop: null
-  - slot_was_set:
-    - requested_slot: null
-  # The action we want to run when the form is submitted.
-  - action: utter_submit
+  - rule: Submit form
+    condition:
+    # Condition that form is active.
+    - active_loop: restaurant_form
+    steps:
+    - action: restaurant_form
+    - active_loop: null
+    - slot_was_set:
+      - requested_slot: null
+    # The action we want to run when the form is submitted.
+    - action: utter_submit
 ```
 
 The last step is to implement a custom action to validate the form slots. Start by
@@ -288,9 +320,9 @@ adding the custom action to your domain:
 
 ```yaml-rasa
 actions:
-# Other actions
-# ...
-- validate_restaurant_form
+  # Other actions
+  # ...
+  - validate_restaurant_form
 ```
 
 Then add a custom action which validates the `cuisine` slot:


Code review comments:
diff_hunk: @@ -57,34 +57,66 @@ deprecated:
 - [Two-Stage-Fallback Policy](./policies.mdx#two-stage-fallback-policy)
 - [Form Policy](./policies.mdx#form-policy)
 
-#### Migrating from the Mapping Policy
+:::tip Automatic migration
+Rasa Open Source can take care of automatically migrating the Mapping Policy,
+the Fallback Policy and the Two-Stage-Fallback Policy for you. To do so, run the
+following command:
+
+```bash
+rasa data convert config
+```
+
+This command will take care of updating your `config.yml`, `domain.yml` and `rules.yml`, while
+making backups of your pre-existing files using the `.bak` suffix.
+
+You can follow the steps below if you wish to do this migration manually.
+Please note that you would still need to [migrate the Form Policy](#migrating-from-the-form-policy) manually.
+:::
+
+#### Manually migrating from the Mapping Policy
 
 If you previously used the [Mapping Policy](./policies.mdx#mapping-policy), you
 can follow the documentation on [FAQs](./chitchat-faqs.mdx) to convert your mapped
 intents to rules. Suppose you previously mapped an intent `ask_is_bot` as follows:
 
-```yaml-rasa
+```yaml-rasa title="domain.yml"
 intents:
  - ask_is_bot:
      triggers: action_is_bot
 ```
 
 This becomes the following rule:
 
-```yaml-rasa
+```yaml-rasa title="rules.yml"
 rules:
 - rule: Rule to map `ask_is_bot` intent
   steps:
   - intent: ask_is_bot
   - action: action_is_bot
 ```
 
-#### Migrating from the Fallback Policy
+And you can safely remove any trigger from your domain:
path: docs/docs/migration-guide.mdx
text: @user1:
```suggestion
And you can safely remove any `triggers:` from your domain:
```