feat(semantic-release): honor ! in commit titles via conventionalcommits preset

ai/rules.mdc

@@ -91,7 +91,7 @@ See [Coding Styleguide Shell Scripts](./coding-styleguide-sh.mdc)
 - Prefer staged validation for non-trivial tasks. While iterating, run only fast, focused checks (type diagnostics, the single affected unit test file). Defer slow checks (browser/e2e/visual tests, builds, full test suites) until the change is complete, unless the change touches exactly what that check proves. Run formatting and linting once the change is complete (before handoff, a commit or a push, whoever does it), not after every edit. For trivial tasks, a single final validation is acceptable.
 - Adjust documentation both in comments and markdown files once you're done
 - Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
-- **Important**: For breaking changes, do not rely on the `!` shorthand (e.g. `feat!:`). This repo's semantic-release config uses the default `conventional-changelog-angular` preset, whose header parser does not recognize `!` — such commits are silently ignored (not even counted as a `feat`/`fix` release). Always add a `BREAKING CHANGE:` footer describing the change instead.
+- For breaking changes, mark the commit or PR title with `!` (e.g. `feat(scope)!:`) and add a `BREAKING CHANGE:` footer that tells consumers what to do. `@peerigon/configs/semantic-release` uses the `conventionalcommits` preset, which honors `!`. If a project still uses the default `angular` preset, `!` is ignored and the `BREAKING CHANGE:` paragraph (at the start of a line, not a heading) is the only trigger, otherwise the merge releases nothing.
 
 ## Consumer-repo uncertainty protocol
 

package.json

@@ -128,6 +128,7 @@
     "@tanstack/eslint-plugin-query": "^5.101.4",
     "@types/eslint-config-prettier": "^6.11.3",
     "@vitest/eslint-plugin": "^1.6.23",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-i18next": "^6.1.5",
     "eslint-plugin-jsx-a11y-x": "^0.2.0",

semantic-release/README.md

@@ -115,3 +115,33 @@ with branch protection rules.
 To prevent stale changelogs, releases fail when a `CHANGELOG.md` file exists in the
 repository. You can bypass this check by setting
 `SEMANTIC_RELEASE_ALLOW_CHANGELOG=true`.
+
+## Commit analysis: `conventionalcommits` preset
+
+The preset uses the `conventionalcommits` preset for both the commit analyzer and the release notes
+generator instead of semantic-release's default `angular` preset. The only functional difference for
+releases is the `!` shorthand:
+
+| Commit message                                       | `angular` (default) | `conventionalcommits` |
+| ---------------------------------------------------- | ------------------- | --------------------- |
+| `feat(scope)!: drop Node 20`                         | **no release**      | major                 |
+| `fix!: change default`                               | **no release**      | major                 |
+| `feat: x` + footer `BREAKING CHANGE: ...`            | major               | major                 |
+| `feat!: x` + footer `BREAKING-CHANGE: ...`           | **no release**      | major                 |
+| `feat: x` + heading `## BREAKING CHANGE` in the body | minor               | minor                 |
+| `fix: x` / `perf: x`                                 | patch               | patch                 |
+| `refactor:`, `docs:`, `chore:`, `build:`, `ci:`      | no release          | no release            |
+
+Note that a heading like `## BREAKING CHANGE` never counts. The footer has to be a paragraph that starts
+with `BREAKING CHANGE:` at the beginning of a line. Because squash merges use the PR title as the commit
+header and the PR description as the body, this applies to PR titles and descriptions as well.
+
+The release notes also look different:
+
+- `BREAKING CHANGES` is rendered as `### ⚠ BREAKING CHANGES` and listed first, including `!` commits
+  (`* **x:** drop Node 20`). With `angular`, only commits with a footer show up there.
+- Section order is Features, Bug Fixes, Performance Improvements, Reverts (`angular`: Bug Fixes first).
+- The version header is `## [2.0.0]` (`angular`: `# [2.0.0]` for minor/major and `## [2.0.0]` for patches).
+
+Still add a `BREAKING CHANGE:` footer to every breaking change: it carries the migration instructions that
+end up in the release notes. Projects with their own `.releaserc` that keep the `angular` preset ignore `!`.

semantic-release/base.js

@@ -36,8 +36,10 @@ export const config = {
           ` && node "${verifyPublishableScript}"`,
       },
     ],
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
+    // The default angular preset ignores the `!` in `feat(scope)!:` and would silently skip
+    // the release unless the body has a `BREAKING CHANGE:` footer. conventionalcommits honors both.
+    ["@semantic-release/commit-analyzer", { preset: "conventionalcommits" }],
+    ["@semantic-release/release-notes-generator", { preset: "conventionalcommits" }],
     [
       "@semantic-release/npm",
       {