diff --git a/packages/docs/content/docs/netlify-cms-migration-guide.mdx b/packages/docs/content/docs/netlify-cms-migration-guide.mdx
index aa91dbf3..8d6d6371 100644
--- a/packages/docs/content/docs/netlify-cms-migration-guide.mdx
+++ b/packages/docs/content/docs/netlify-cms-migration-guide.mdx
@@ -12,6 +12,20 @@ Static CMS is a fork of Netlify CMS. Many changes have been made, some big, some
 - CMS must be explicitly initiated now by calling `CMS.init()`
 - Passing a config to `CMS.init()` will now completely override `config.yml` (they are now exclusive), instead of being merged with `config.yml`
 - A [new markdown editor](/docs/widget-markdown) has been added. It comes with a new [shortcode](/docs/widget-markdown#shortcodes) system, old editor components no longer work.
+- The `sortable_fields` configuration option has been slightly changed, as we now allow a [default sorting option](/docs/collection-overview#sortable_fields).
+  Migrate it by exchanging
+  ```yaml
+  sortable_fields:
+   - field1
+   - field2
+  ```
+  with
+  ```yaml
+  sortable_fields:
+    fields:
+     - field1
+     - field2
+   ```
 - Support in the List Widget for the `field` property has been dropped. A single field in the `fields` property [achieves the same behavior](/docs/widget-list).
 - Custom widget creation has changed slightly. React class components have been deprecated. Widgets should all be [functional components](https://reactjs.org/docs/components-and-props.html#function-and-class-components) now. There have also been changes to how custom widgets are registered and the properties passed to the controls and previews. See [custom widgets](/docs/custom-widgets) for full details.