Added notes on UPGRADING.md

Author: cmaglie

docs/UPGRADING.md

@@ -4,6 +4,51 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## Unreleased
 
+### Change in `github.com/arduino/arduino-cli/commands/*` package functions signature
+
+The `error` returned from each function in this package (and his subpackages) has been changed into a gRPC
+status `*status.Status` object.
+The rationale behind this change is that each function in the `commands` package has a direct counterpart in
+the gRPC server API, but the `error` type do not map exactly the way the gRPC protocol handles error.
+The `Status` object may be decorated with `Status.Details` that may give, in some circumstances, more
+detailed information on the cause of a failure.
+
+From the "gRPC client" point of view, this change should not break because a failing gRPC call is still
+failing after this change.
+
+From the "golang import" point of view, this is a breaking change because where previously we had an `error`
+now we get a `*status.Status`. Let's look, for example, at the `board.Details` function:
+
+```go
+func Details(ctx context.Context, req *rpc.BoardDetailsRequest) (*rpc.BoardDetailsResponse, error) {
+```
+
+Now has been changed to:
+
+```go
+func Details(ctx context.Context, req *rpc.BoardDetailsRequest) (*rpc.BoardDetailsResponse, *status.Status) {
+```
+
+so if previously we used to handle the error in the usual golang way:
+
+```go
+detailsResp, err := board.Details(context.Background(), detailsReq)
+if err != nil {
+    fmt.Println("Error getting board details:", err)
+    return
+}
+```
+
+now we must unwrap the error message from the `Status` object:
+
+```go
+detailsResp, stat := board.Details(context.Background(), detailsReq)
+if stat != nil {
+    fmt.Println("Error getting board details:", stat.Message())
+    return
+}
+```
+
 ### Change public library interface
 
 #### `github.com/arduino/arduino-cli/i18n` package