docs: improve breaking change handling (#2207)

- update issue template
- update `CONTRIBUTING.md`
- add semver checker to CI

---------

Co-authored-by: Asmir Avdicevic <asmir.avdicevic64@gmail.com>

Author: dignifiedquire

.github/pull_request_template.md

@@ -2,6 +2,10 @@
 
 <!-- A summary of what this pull request achieves and a rough list of changes. -->
 
+## Breaking Changes
+
+<!-- Optional, if there are any breaking changes document them, including how to migrate older code. -->
+
 ## Notes & open questions
 
 <!-- Any notes, remarks or open questions you have to make about the PR. -->
@@ -11,3 +15,4 @@
 - [ ] Self-review.
 - [ ] Documentation updates if relevant.
 - [ ] Tests if relevant.
+- [ ] All breaking changes documented.

.github/workflows/ci.yml

@@ -72,6 +72,32 @@ jobs:
       env:
         RUST_LOG: ${{ runner.debug && 'TRACE' || 'DEBUG' }}
 
+
+  check_semver:
+    runs-on: ubuntu-latest
+    env:
+      RUSTC_WRAPPER: "sccache"
+      SCCACHE_GHA_ENABLED: "on"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install sccache
+        uses: mozilla-actions/sccache-action@v0.0.4
+
+      - name: Setup Environment (PR)
+        if: ${{ github.event_name == 'pull_request' }}
+        shell: bash
+        run: |
+          echo "HEAD_COMMIT_SHA=$(git rev-parse origin/${{ github.base_ref }})" >> ${GITHUB_ENV}
+      - name: Check semver
+        # uses: obi1kenobi/cargo-semver-checks-action@v2
+        uses: n0-computer/cargo-semver-checks-action@feat-baseline
+        with:
+          package: iroh, iroh-base, iroh-bytes, iroh-cli, iroh-dns-server, iroh-gossip, iroh-metrics, iroh-net, iroh-sync
+          baseline-rev: ${{ env.HEAD_COMMIT_SHA }}
+          use-cache: false
+
   check_fmt_and_docs:
     timeout-minutes: 30
     name: Checking fmt and docs

.github/workflows/commit.yml

@@ -12,3 +12,5 @@ jobs:
       - name: check-for-cc
         id: check-for-cc
         uses: agenthunt/conventional-commit-checker-action@v1.0.0
+        with:
+          pr-title-regex: "^(.+)(?:(([^)s]+)))?!?: (.+)"

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Here are some of the ways in which you can contribute:
 
 ## Discussions
 
-If you want to ask a question to understand a concept regarding Iroh, or need help working with Iroh, please check the [Discussions][discussions]. If you don't find a thread that fits your needs, feel free to create a new one. 
+If you want to ask a question to understand a concept regarding Iroh, or need help working with Iroh, please check the [Discussions][discussions]. If you don't find a thread that fits your needs, feel free to create a new one.
 
 ## Issues
 
@@ -21,7 +21,7 @@ If you would like to suggest a new feature in Iroh, [create a new issue][newissu
 Code contributions to Iroh are greatly appreciated. Here is the general workflow you should follow:
 
 1. **State in the associated issue your desire to work on it**
-  
+
    If there is no issue for the work you would like to do, please open one. This helps reduce duplicated efforts and give contributors the help and guidance they might need.
 
 2. **Write some code!**
@@ -38,7 +38,7 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow
      - Comment your code. It will be useful for your reviewer and future contributors.
 
    - **Pull request titles**
- 
+
      - Iroh pull requests titles look like this: `type(crate): description`
 
        | **`type`** | **When to use** |
@@ -52,11 +52,13 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow
        | `deps`     | Dependency only updates |
        | `chore`    | Changes to the build process or auxiliary tools and libraries |
 
-  
+
        **`crate`** is the rust crate containing your changes.
 
        **`description`** is a short sentence that summarizes your changes.
 
+       If there is a breaking change please use a `!` in the commit message to denote this, eg. `feat(iroh)!: break the world`.
+
    - **Pull request descriptions**
 
      Once you open a pull request, you will be prompted to follow a template with three simple parts:
@@ -65,6 +67,10 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow
 
        A summary of what your pull request achieves and a rough list of changes.
 
+     - **Breaking Changes**
+
+       Optional, if there are any breaking changes document them, including how to migrate older code.
+
      - **Notes & open questions**
 
        Notes, open questions and remarks about your changes.
@@ -74,6 +80,7 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow
        - **Self review**: We ask you to thoroughly review your changes until you are happy with them. This helps speed up the review process.
        - **Add documentation**: If your change requires documentation updates, make sure they are properly added.
        - **Tests**: If your code creates a new feature, when possible add tests for this. If they fix a bug, a regression test is recommended as well.
+       - **Breaking Changes**: All breaking changes need to be documented.
 
 
 4. **Review process**