docs: update

Author: alessio-perugini

Diff for: docs/UPGRADING.md

@@ -4,6 +4,28 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## 0.36.0
 
+### The gRPC `cc.arduino.cli.commands.v1.PlatformRelease` has been changed.
+
+We've added a new field called `incompatible`. This field indicates if the current platform release is installable or
+not. It may happen that a platform doesn't have a dependency available for an OS, in such cases, if we try to install
+the platform it will fail. The new field can be used to know upfront if a specific release is installable.
+
+### The gRPC `cc.arduino.cli.commands.v1.PlatformSummary` has been changed.
+
+We've added a new field called `latest_compatible_version`. This field indicates the latest version that can be
+successfully installed for the current OS. The `latest_version` field cannot guarantee such property.
+
+### `core list` now returns only the latest version that can be installed.
+
+Previously, we showed the latest version without checking if all the dependencies were available in the current OS. Now,
+the latest version will always point to an installable one even if a newer incompatible one is present.
+
+### `core upgrade` and `core install` will install the latest compatible version.
+
+Previously, we'd have tried the installation/upgrade of a core even if all the required tools weren't available in the
+current OS. Now we check this upfront, and allowing the installation of incompatible versions only if a user explicitly
+provides it like: `core install arduino:[email protected]`
+
 ### gRPC `cc.arduino.cli.commands.v1.LibrarySearchRequest` message has been changed.
 
 The `query` field has been removed, use `search_args` instead.