Reduce the frequency of breaking changes going forward

.github/workflows/check.yml

@@ -6,7 +6,6 @@ permissions:
 
 on:
   pull_request:
-    branches: ["main"]
 
 jobs:
   check:
@@ -29,3 +28,4 @@ jobs:
 
       # Run checks with cached dependencies
       - run: nix develop --command just ci
+

.github/workflows/semver.yml

@@ -0,0 +1,31 @@
+name: Semver
+
+permissions:
+  id-token: write
+  contents: read
+
+on:
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - uses: DeterminateSystems/flake-checker-action@main
+
+      # Cache Rust dependencies and build artifacts
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      # Run checks with cached dependencies
+      - run: nix develop --command just semver

CLAUDE.md

@@ -90,6 +90,13 @@ Key architectural rule: The CDN/relay does not know anything about media. Anythi
 - Rust tests are integrated within source files
 - Async tests that sleep should call `tokio::time::pause()` at the start to simulate time instantly
 
+## Branching Strategy
+
+- **`main`**: Stable branch for patch releases. Only non-breaking fixes and additions.
+- **`dev`**: Development branch for breaking API changes. PRs with major API changes should target `dev`.
+- When ready for a new minor/major release, merge `dev` into `main`.
+- `cargo-semver-checks` enforces this on PRs to `main`.
+
 ## Workflow
 
 When making changes to the codebase:

flake.nix

@@ -62,6 +62,7 @@
           cargo-edit
           cargo-hack
           cargo-sweep
+          cargo-semver-checks
         ];
 
         # JavaScript dependencies

justfile

@@ -11,7 +11,7 @@ default:
 # Install any dependencies.
 install:
 	bun install
-	cargo install --locked cargo-shear cargo-sort cargo-upgrades cargo-edit cargo-hack cargo-sweep
+	cargo install --locked cargo-shear cargo-sort cargo-upgrades cargo-edit cargo-hack cargo-sweep cargo-semver-checks release-plz
 
 # Alias for dev.
 all: dev
@@ -368,6 +368,16 @@ ci:
 	echo "Checking all feature combinations..."
 	cargo hack check --workspace --each-feature --no-dev-deps
 
+# Check semver compatibility against crates.io
+# requires: cargo install cargo-semver-checks
+# libmoq is an internal C-ABI crate and is intentionally excluded from published-crate semver checks.
+semver:
+	cargo semver-checks check-release --workspace --exclude libmoq
+
+# Update versions and changelogs via release-plz
+bump:
+	release-plz update
+
 # Run the unit tests
 test:
 	#!/usr/bin/env bash