From c5b597d0ae9d20574b2352c45c4d38afef498b10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Agust=C3=ADn=20Borgna?=
 <121866228+aborgna-q@users.noreply.github.com>
Date: Fri, 18 Oct 2024 17:03:08 +0100
Subject: [PATCH] docs: Add help docs about `semver-checks` (#1590)

Also makes both `release-plz` and `release-please` mark their PRs with
`release` labels.
---
 DEVELOPMENT.md             | 20 ++++++++++++++++++++
 justfile                   |  5 +++++
 release-please-config.json |  3 ++-
 release-plz.toml           |  1 +
 4 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 00f4d11b4..265d5dcb4 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -66,6 +66,26 @@ cargo +nightly miri test
 
 Run `just` to see all available commands.
 
+### 💥 API-breaking changes
+
+Any breaking change in the public Rust APIs will cause the next release to be a
+major version bump. You can check the next release version [draft release
+PR](https://github.com/CQCL/hugr/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) on
+github.
+
+Use `cargo semver-checks` to alert you of any problematic changes.
+Replace the baseline-rev with a commit hash if your branch is not up-to-date with the main branch.
+
+```bash
+# Ensure you have cargo-semver-checks installed
+cargo install cargo-semver-checks --locked
+# Check for breaking changes against the main branch
+cargo semver-checks --baseline-rev origin/main
+```
+
+These checks are also run on the CI. You will see a warning comment on your PR
+if you introduce a breaking change.
+
 ## 💅 Coding Style
 
 The rustfmt tool is used to enforce a consistent rust coding style. The CI will fail if the code is not formatted correctly.
diff --git a/justfile b/justfile
index 7f982be13..8049c879c 100644
--- a/justfile
+++ b/justfile
@@ -59,9 +59,14 @@ gen-extensions:
     cargo run -p hugr-cli gen-extensions -o specification/std_extensions
     cp -r specification/std_extensions/* hugr-py/src/hugr/std/_json_defs/
 
+# Build the python documentation in hugr-py/docs.
 build-py-docs:
     cd hugr-py/docs && ./build.sh
 
+# Run rust semver-checks to detect breaking changes since the last release.
+semver-checks:
+    cargo semver-checks
+
 # Runs a rust and a python command, depending on the `language` variable.
 #
 # If `language` is set to `rust` or `python`, only run the command for that language.
diff --git a/release-please-config.json b/release-please-config.json
index 73be2530f..54e6bdf7b 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -4,6 +4,7 @@
     "bump-minor-pre-major": true,
     "bump-patch-for-minor-pre-major": true,
     "initial-version": "0.0.0",
+    "extra-label": "release",
     "packages": {
         "hugr-py": {
             "release-type": "python",
@@ -62,4 +63,4 @@
             "hidden": true
         }
     ]
-}
+}
\ No newline at end of file
diff --git a/release-plz.toml b/release-plz.toml
index ed9e738ed..d93045609 100644
--- a/release-plz.toml
+++ b/release-plz.toml
@@ -11,6 +11,7 @@ pr_draft = true
 # (This would normally only be enabled once there are multiple packages in the workspace)
 git_tag_name = "{{ package }}-v{{ version }}"
 git_release_name = "{{ package }}: v{{ version }}"
+pr_labels = ["release"]
 
 # Only create releases / push to crates.io after merging a release-please PR.
 # This lets merge new crates to `main` without worrying about accidentally creating