[skip changelog] Update contributions guidelines and PR template to add labeling and increase focus on breaking changes (#1039)

* [skip changelog] Update contributions guidelines and PR template to add labeling and increase focus on breaking changes

* Add better explanation of breaking changes based on suggestions

* Reword breaking change paragraph in docs and Arduino CLI name in pull request template

* Revert typo

* [skip changelog] Update breaking changes policy

* [skip changelog] Fix some docs issues

* [skip changelog] Remove unused link from docs

Co-authored-by: Silvano Cerza <[email protected]>

Author: Roberto Sora

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,6 +6,7 @@
       [our contributing guidelines](https://arduino.github.io/arduino-cli/latest/CONTRIBUTING/#pull-requests)
 - [ ] Tests for the changes have been added (for bug fixes / features)
 - [ ] Docs have been added / updated (for bug fixes / features)
+- [ ] `UPGRADING.md` has been updated with a migration guide (for breaking changes)
 
 * **What kind of change does this PR introduce?**
 <!-- Bug fix, feature, docs update, ... -->
@@ -16,8 +17,10 @@
 * **What is the new behavior?**
 <!-- if this is a feature change -->
 
-- **Does this PR introduce a breaking change?**
-<!-- What changes might users need to make in their workflow or application due to this PR? -->
+- **Does this PR introduce a breaking change, and is
+[titled accordingly](https://arduino.github.io/arduino-cli/latest/CONTRIBUTING/#breaking)?**
+<!-- If this PR is merged, will any users need to change their code, command-line invocations, build scripts or data files
+when upgrading from an older version of Arduino CLI? -->
 
 * **Other information**:
 <!-- Any additional information that could help the review process -->

docs/CONTRIBUTING.md

@@ -54,6 +54,11 @@ submitting a PR:
 - PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good record of **what** change is being
   made in the title; **why** it was made will go in the PR description, along with a link to a GitHub issue if it
   exists.
+- <a id="breaking"></a> If the PR contains a breaking change, please start the commit message and PR title with the
+  string **[breaking]**. Don't forget to describe in the PR description and in the [`UPGRADING.md`][upgrading-file] file
+  what changes users might need to make in their workflow or application due to this PR. A breaking change is a change
+  that forces users to change their code, command-line invocations, build scripts or data files when upgrading from an
+  older version of Arduino CLI.
 - Write tests for the code you wrote.
 - Open your PR against the `master` branch.
 - Maintain **clean commit history** and use **meaningful commit messages**. PRs with messy commit history are difficult
@@ -421,3 +426,4 @@ If your PR doesn't need to be included in the changelog, please start the commit
 [npm-install-docs]: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
 [poetry-website]: https://python-poetry.org/
 [poetry-docs]: https://python-poetry.org/docs/
+[upgrading-file]: UPGRADING.md

docs/UPGRADING.md

@@ -0,0 +1,5 @@
+# Upgrading
+
+Here you can find a list of migration guides to handle breaking changes between releases of the CLI.
+
+## Unreleased

docsgen/go.sum

@@ -152,6 +152,7 @@ github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+o
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
 github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.2.0/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/pty v1.1.8/go.mod h1:O1sed60cT9XZ5uDucP5qwvh+TE3NnUj51EiZO/lmSfw=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=

mkdocs.yml

@@ -58,6 +58,7 @@ markdown_extensions:
 nav:
   - Documentation Home: index.md
   - installation.md
+  - UPGRADING.md
   - getting-started.md
   - command-line-completion.md
   - CONTRIBUTING.md