[skip changelog] Update UPGRADING.md with new breaking changes (#1101)

* [skip changelog] Update UPGRADING.md with new breaking changes

* [skip changelog] Apply suggestions from code review
Co-authored-by: per1234 <accounts@perglass.com>
Co-authored-by: per1234 <accounts@perglass.com>

docs/UPGRADING.md

@@ -37,3 +37,34 @@ The `debug.xxx=yyy` definitions above may be supplied and overlayed in the usual
 - on `platform.txt`: definition here will be shared through all boards in the platform
 - on `boards.txt` as part of a board definition: they will override the global platform definitions
 - on `programmers.txt`: they will override the boards and global platform definitions if the programmer is selected
+
+### Binaries export must now be explicitly specified
+
+Previously, if the `--build-path` was not specified, compiling a Sketch would copy the generated binaries in
+`<sketch_folder>/build/<fqbn>/`, uploading to a board required that path to exist and contain the necessary binaries.
+
+The `--dry-run` flag was removed.
+
+The default, `compile` does not copy generated binaries to the sketch folder. The `--export-binaries` (`-e`) flag was
+introduced to copy the binaries from the build folder to the sketch one. `--export-binaries` is not required when using
+the `--output-dir` flag. A related configuration key and environment variable has been added to avoid the need to always
+specify the `--export-binaries` flag: `sketch.always_export_binaries` and `ARDUINO_SKETCH_ALWAYS_EXPORT_BINARIES`.
+
+If `--input-dir` or `--input-file` is not set when calling `upload` the command will search for the deterministically
+created build directory in the temp folder and use the binaries found there.
+
+The gRPC interface has been updated accordingly, `dryRun` is removed.
+
+### Programmers can't be listed anymore using `burn-bootloader -P list`
+
+The `-P` flag is used to select the programmer used to burn the bootloader on the specified board. Using `-P list` to
+list all the possible programmers for the current board was hackish.
+
+This way has been removed in favour of `board details <fqbn> --list-programmers`.
+
+### `lib install --git-url` and `--zip-file` must now be explicitly enabled
+
+With the introduction of the `--git-url` and `--zip-file` flags the new config key `library.enable_unsafe_install` has
+been added to enable them.
+
+This changes the ouput of the `config dump` command.