From e04a7e77cf3c7652e75cfa903007bfcc00c512f3 Mon Sep 17 00:00:00 2001
From: Alexandre Bodin <bodin.alex@gmail.com>
Date: Thu, 17 Dec 2020 15:48:58 +0100
Subject: [PATCH] Update migration guide

---
 .../migration-guide-3.3.x-to-3.4.0.md         | 32 ++++++++++++++++---
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/v3.x/migration-guide/migration-guide-3.3.x-to-3.4.0.md b/docs/v3.x/migration-guide/migration-guide-3.3.x-to-3.4.0.md
index 062ef7774c..c067dba0a2 100644
--- a/docs/v3.x/migration-guide/migration-guide-3.3.x-to-3.4.0.md
+++ b/docs/v3.x/migration-guide/migration-guide-3.3.x-to-3.4.0.md
@@ -10,9 +10,33 @@ Not updating your **extensions** can break your app in unexpected ways that we c
 
 ## Migration
 
-1. First, update your app as usual by following the basic [version update guide](../guides/update-version.md) and then come back here
-2. Download this script: <a :href="$withBase('/assets/migrations/scripts/migrate-3.4.0.js')" download>migrate-3.4.0.js</a>
-3. Execute it with the following command: `node migrate-3.4.0.js [path-to-your-project]`
-4. Delete the script (optional)
+### Update the application dependencies
+
+First, update the application dependencies as usual by following the basic [version update guide](../guides/update-version.md)
+
+### Migrate configurations
+
+In this new release we are introducing a new feature that will allow sorting on relations in the list view.
+Currently this is disabled by default. To enable it, you would need to update every field configuration manually.
+
+To help with this, here is a migration script to enable the sorting in the existing configuration.
+
+> This migration step is **not required**. If you prefer doing the configuration updates manually, you can ignore it.
+
+> This migration script changes the configuration stored in database. If you upgrade an application running in production, you will have to run the script on the production envrionment too.
+
+What the script will do:
+
+```
+for each contentType
+  -> for each sortable relational field
+    -> enable sorting in the list view
+```
+
+**Run the script**
+
+1. Download the migration script: <a :href="$withBase('/assets/migrations/scripts/migrate-3.4.0.js')" download>migrate-3.4.0.js</a>
+2. Execute it with the following command: `node migrate-3.4.0.js [path-to-your-project]`
+3. Delete the script
 
 🎉 Congrats, your application has been migrated!