Updated upgrade docs

docs/upgrades/upgrade_350_400.rst

@@ -1,13 +1,61 @@
 Upgrading from 3.5.0 to 4.0.0
 =============================
 
-Version 4.0.0 is a major release where all previous deprecations are removed.
+Version 4.0.0 is a major release where all previous deprecations have been removed and several
+breaking changes have been introduced.
 
-Configuration changes
----------------------
+Removed ``RenderContentEvent``
+------------------------------
+
+Event ``RenderContentEvent`` and the associated class ``SiteApiEvents`` have been removed. If you
+used this event, upgrade by using new ``RenderViewEvent`` instead.
+
+Removed loading Content relations by ID
+---------------------------------------
+
+Using Content ID with ``RelationService`` methods ``loadFieldRelation()`` and
+``loadFieldRelations()`` has been removed. Now, only Content instance is allowed. If you used these
+methods directly, you can upgrade your code by providing Content instance instead of the ID.
+
+Enabled view fallback without a subrequest
+------------------------------------------
+
+View fallback without a subrequest has been enabled by default. If you depended on view fallback
+being disabled or not avoiding a subrequest, upgrade by explicitly configuring the options as
+needed:
+
+.. code-block:: yaml
+
+    ezpublish:
+        system:
+            frontend_group:
+                ng_site_api:
+                    fallback_to_secondary_content_view: false
+                    fallback_without_subrequest: false
+
+Enabled filtering out non-visible items in Query Types
+------------------------------------------------------
+
+Previously, you had to explicitly set the condition on Location visibility when configuring Query
+Types. By default, both visible and non visible Locations were returned. Now, both Content and
+Location Query Types will return only visible items by default. This can be overridden on the Query
+Type level by explicitly configuring visibility.
+
+You can also configure the default behaviour by the siteaccess:
+
+.. code-block:: yaml
+
+    ezpublish:
+        system:
+            frontend_group:
+                ng_site_api:
+                    show_hidden_items: true
+
+Restructured configuration
+--------------------------
 
 Semantic configuration located under eZ Platform siteaccess aware configuration has been renamed and
-consolidated under `ng_site_api` key.
+consolidated under ``ng_site_api`` key.
 
 - ``ng_fallback_to_secondary_content_view`` has been renamed to ``fallback_to_secondary_content_view``
 - ``ng_fallback_without_subrequest`` has been renamed to ``fallback_without_subrequest``
@@ -20,7 +68,7 @@ under ``ng_site_api`` key under eZ Platform siteaccess aware configuration:
 - ``override_url_alias_view_action`` has been renamed to ``site_api_is_primary_content_view``
 - ``fail_on_missing_fields`` has been renamed to ``fail_on_missing_field``
 
-Previous configuration:
+Old configuration:
 
 .. code-block:: yaml
 
@@ -40,7 +88,7 @@ Previous configuration:
                 render_missing_field_info: true
                 named_objects: []
 
-New configuration:
+Upgraded configuration:
 
 .. code-block:: yaml
 
@@ -61,7 +109,7 @@ New configuration:
 Key for Site API content view configuration has been renamed from ``ngcontent_view`` to
 ``ng_content_view``:
 
-Previous configuration:
+Old configuration:
 
 .. code-block:: yaml
 
@@ -70,7 +118,7 @@ Previous configuration:
             frontend_group:
                 ngcontent_view: []
 
-New configuration:
+Upgraded configuration:
 
 .. code-block:: yaml
 
@@ -84,7 +132,7 @@ Named object configuration has renamed keys used for named object types:
 - ``location`` has been renamed to ``locations``
 - ``tag`` has been renamed to ``tags``
 
-Previous configuration:
+Old configuration:
 
 .. code-block:: yaml
 
@@ -99,7 +147,7 @@ Previous configuration:
                     tag:
                         colors: 456
 
-New configuration:
+Upgraded configuration:
 
 .. code-block:: yaml