From 3afdf4c238d0f3575f6764892cae0d00257a6f39 Mon Sep 17 00:00:00 2001
From: Charles Mulder <chmulder@redhat.com>
Date: Wed, 29 Apr 2026 10:16:25 +0100
Subject: [PATCH] fix(release): set useCommitScope to true to prevent global
 major bumps

---
 CLAUDE.md       | 13 +++++++++++++
 CONTRIBUTING.md | 16 ++++++++++++++++
 nx.json         |  5 +++--
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 394a0f8a..a8a95f62 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,6 +29,19 @@ Husky is configured:
 - `npm ci` is used in CI (not `npm install`)
 - Only affected packages are linted/tested/built (`nx affected`)
 
+## Nx Release Configuration
+
+**CRITICAL: Do not change `useCommitScope` in `nx.json`**
+
+`nx.json` has `"conventionalCommits": { "useCommitScope": true }` (line 73). This controls how breaking changes affect version bumps:
+
+- `useCommitScope: true` (current, REQUIRED) — Breaking changes only bump packages named in commit scope. Example: `feat(rbac)!: breaking change` bumps rbac to major, other packages get patch for dependency update.
+- `useCommitScope: false` (DANGEROUS) — Breaking changes bump ALL packages with modified files to major, regardless of commit scope. Causes `preserveMatchingDependencyRanges` failures when shared package jumps major but clients depend on `^2.x`.
+
+**Why this matters:** Shared package is a dependency of all clients. With `useCommitScope: false`, any breaking change touching shared's files triggers major bumps across all 15 packages, breaking semver ranges and failing releases.
+
+See: Nx source `packages/nx/src/command-line/release/utils/semver.ts:44`
+
 ## Working with This Repo
 
 - Never directly call CLI tools (`jest`, `eslint`, `tsc`). Use npm scripts.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a8cf8ad7..356c610c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -86,3 +86,19 @@ See [docs/testing-guidelines.md](docs/testing-guidelines.md) for details on test
 ## Release Process
 
 Releases are automated via Nx Release on the `main` branch. Each package is independently versioned based on conventional commit history. Do not manually bump versions.
+
+### Critical Configuration: `useCommitScope`
+
+**Do not change `"useCommitScope": true` in `nx.json` (line 73).**
+
+This setting controls how breaking changes affect version bumps:
+
+- **`true` (current)**: Breaking changes only bump packages named in commit scope
+  - Example: `feat(rbac)!: breaking change` → rbac gets major bump, other packages get patch for dependency update
+  - Prevents cascading major bumps across unrelated packages
+
+- **`false` (dangerous)**: Breaking changes bump ALL packages with modified files to major
+  - Causes `preserveMatchingDependencyRanges` failures when shared package jumps major but clients still depend on `^2.x`
+  - Results in failed releases
+
+Since `packages/shared/` is a dependency of all 15 client packages, setting `useCommitScope: false` would cause any breaking change touching shared files to trigger major bumps across the entire monorepo.
diff --git a/nx.json b/nx.json
index 2b2bf295..3ef2f4e6 100644
--- a/nx.json
+++ b/nx.json
@@ -70,7 +70,7 @@
       "manifestRootsToUpdate": ["{projectRoot}", "{projectRoot}/dist"]
     },
     "conventionalCommits": {
-      "useCommitScope": false
+      "useCommitScope": true
     },
     "changelog": {
       "workspaceChangelog": false,
@@ -138,5 +138,6 @@
         "ciTargetName": "e2e-ci"
       }
     }
-  ]
+  ],
+  "analytics": false
 }