feat(release): enable ! notation for breaking changes in semantic-release by brtbrt · Pull Request #1658 · Telefonica/mistica-web

brtbrt · 2026-07-16T12:24:11Z

Summary

Fix the ! notation for breaking changes in commit subjects (feat(scope)!: description), which used to be validated on PRs, but ignored as a major when releasing.

The whys

ci workflow is using commit-analyzer 13.0.1 (the action is using it) . uses: amannn/action-semantic-pull-request@v5
release was using another one: (10.0.0?) which was buggy about this

the two workflows used to work with different seantics, risky.

Changes

Core Fix

Upgrade @semantic-release/commit-analyzer from 10.0.0 to 13.0.1 (includes conventional-commits-parser 6.4.0)
Add explicit parserOpts.breakingHeaderPattern configuration to enable ! notation parsing
Update release workflow to pass NPM token to validate job for proper dry-run

Testing & Verification!

Verified ! notation correctly triggers major version bumps (e.g., 17.1.0 → 18.0.0 for feat(ci)!:)
Tested with semantic-release dry-run to confirm breaking change detection works

https://github.com/Telefonica/mistica-web/actions/runs/29528124907/job/87721546071
https://github.com/Telefonica/mistica-web/actions/runs/29513716048/job/87673343062

[4:03:02 PM] [semantic-release] › ℹ  The next release version is 18.0.0

Related Issues

Fixes #1657
Tracks #1660 (upstream issue - TODO to remove breakingHeaderPattern when fixed)

Migration

Breaking changes can now use the shorter syntax:

feat(api)!: remove legacy endpoint

Instead of:

feat(api): remove legacy endpoint

BREAKING CHANGE: legacy endpoint removed

Both syntaxes still work. The ! notation is now the preferred approach.

Testing

✅ Verified feat(ci)!: ... correctly detected as major version bump
✅ Verified dry-run shows correct next version
✅ Verified CI validates PR titles with semantic-release action

closes #1657

…eaking change support The ! notation for breaking changes (e.g., feat(scope)!:) requires conventional-commits-parser@3.3.0+. Commit-analyzer v10 includes this. Fixes #1657

Adds a validate job that runs semantic-release --dry-run to show what version will be bumped. The release job now depends on validate and requires manual approval (via production environment), allowing reviewers to check the dry-run output before proceeding. Relates to #1657

github-actions · 2026-07-16T12:27:12Z

Size stats

	master	this branch	diff
Total JS	15.8 MB	15.8 MB	-1 B
JS without icons	1.91 MB	1.91 MB	-1 B
Lib overhead	93 kB	93 kB	0 B
Lib overhead (gzip)	20.5 kB	20.5 kB	0 B

Copilot

Pull request overview

This PR updates the repo’s semantic-release setup so that Conventional Commits breaking changes using the ! notation (e.g. feat(scope)!:) are recognized correctly, and introduces a pre-release validation step that runs semantic-release --dry-run before the actual release proceeds.

Changes:

Upgraded @semantic-release/commit-analyzer to ^10.0.0 (and updated yarn.lock) to support ! breaking-change parsing.
Added a new validate job in the release workflow to run semantic-release --dry-run and gate the release job behind it.
Wired release to depend on validate, keeping the environment: production approval gate for the actual publish.

Reviewed changes

Copilot reviewed 2 out of 12 changed files in this pull request and generated 2 comments.

File	Description
`package.json`	Adds `@semantic-release/commit-analyzer@^10.0.0` to address breaking-change `!` parsing.
`yarn.lock`	Locks the new analyzer version and its updated conventional-commits parser dependency chain.
`.github/workflows/release.yml`	Adds a `validate` dry-run job and makes `release` depend on it.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

        "@semantic-release/changelog": "^6.0.1",
+        "@semantic-release/commit-analyzer": "^10.0.0",
        "@semantic-release/git": "^10.0.1",


github-actions · 2026-07-16T12:29:49Z

Deploy preview for mistica-web ready!

Project:	`mistica-web`
Status:	✅ Deploy successful!
Preview URL:	https://mistica-9ejb5p1te-flows-projects-65bb050e.vercel.app
Latest Commit:	`a18db05`

Deployed with vercel-action

Marcosld · 2026-07-16T12:33:18Z

I would not add a forced dry run validation. I'd just add a checkbox into the release job to perform a dry run.

github-actions · 2026-07-16T12:35:14Z

Accessibility report
✔️ No issues found

ℹ️ You can run this locally by executing yarn audit-accessibility.

Adds custom releaseRules to @semantic-release/commit-analyzer to ensure commits marked as breaking (via ! notation or BREAKING CHANGE footer) trigger major releases. This explicitly handles the breaking flag that may not be recognized by default with the angular preset. See #1657

brtbrt · 2026-07-16T13:04:55Z

Update: Custom releaseRules Configuration

Added explicit to the plugin to ensure breaking changes are properly recognized.

Why this is needed

The angular preset alone does not reliably recognize the feat(scope)! notation for breaking changes (see #3757, #231). By adding explicit releaseRules with { breaking: true, release: 'major' }, we ensure that commits marked as breaking (by the parser recognizing the ! notation) will trigger major releases.

What was added

"releaseRules": [
  { "breaking": true, "release": "major" },
  { "revert": true, "release": "patch" },
  { "type": "feat", "release": "minor" },
  { "type": "fix", "release": "patch" },
  { "type": "perf", "release": "patch" },
  { "scope": "no-release", "release": false }
]

The key rule is the first one: when a commit's breaking flag is true (set by conventional-commits-parser@6+ when it sees !), it triggers a major release.

Add explicit note that the ! notation is not supported by semantic-release in the current configuration. Breaking changes must use the BREAKING CHANGE: footer in the commit body instead. See #1657

Add a validation step that rejects any PR title containing the ! character, since the ! notation for breaking changes is not supported by semantic-release.

… jobs Move CLI argument validation from the release job to the validate job. Both jobs now use the same sanitized args, ensuring the dry-run shows the exact version that will be released. Output safe_args from validate job and pass to release job via needs.

Link to issue #1660 which tracks upstream semantic-release issues blocking ! notation support. When those are resolved, these TODOs should be addressed to re-enable the shorter breaking change syntax.

… ! notation support Fixes breaking change detection for ! notation in commit subjects. Version 13.0.1 includes conventional-commits-parser 6.4.0 which properly parses the ! prefix as a breaking change indicator per the Angular convention.

Disable the ! notation guard to test if semantic-release properly detects breaking changes with the new configuration.

…mantic-release supports ! notation

brtbrt · 2026-07-16T19:41:29Z

I would not add a forced dry run validation. I'd just add a checkbox into the release job to perform a dry run.
I like it, but I'd run it twice each time? it'd be cumbersome and even more error-prone

…antic-release supports ! notation

…llow caret updates

…ncies

Marcosld · 2026-07-21T10:10:44Z

                      feat
                      chore
                      revert
+                  requireScope: false


why this change?

Makes the scope optional (feat: … and feat(button): … both pass). It is the action's default.
I set it explicitly to document the intent and stay consistent with semantic-release, which does not require a scope either.

Marcosld · 2026-07-21T10:11:51Z

                description: 'CLI args'
                required: false
                default: ''
+            skipValidation:


I would change this the other way around (checkbox to enable dryrun). You can even simplify and have just 1 parametrizable job (the user can run it with dry run enabled or not, it doesn't have 2 steps)

Happy to collapse it into a single parametrizable job, but not to invert the flag. Validation stays default-on. An opt-in safety check is one that gets forgotten exactly when it matters. skipValidation is a deliberate opt-out, not the other way around.
better safe than sorry.

The only case when this really matters is when you publish a breaking change as part of a minor/patch version. Don't make everyone go through 2 steps for something that happened once in the last 2 years.

Marcosld · 2026-07-21T10:16:06Z

+                    "preset": "angular",
+                    "_comment": "TODO #1660: Remove breakingHeaderPattern once semantic-release angular preset supports ! notation natively",
+                    "parserOpts": {
+                        "breakingHeaderPattern": "^(\\w*)(?:\\((.*)\\))?!: (.*)$"
+                    }


You resolved my previous comment but didn't change the preset to conventional-commits

Good catch — the analyzer alone was not enough. release-notes-generator parses commits independently, so without the same override a feat!: … bumps the major version but still renders as a plain feature in the CHANGELOG. I have applied breakingHeaderPattern to both plugins, so ! is now handled consistently.

We are staying on the angular preset to keep our existing changelog format. breakingHeaderPattern is the only gap for ! support, and it is now covered in both places. TODO #1660 tracks removing the overrides once angular supports ! natively. Resolving this.

Why do you resolve the conversation?

That's probably because in the config we are setting preset to angular in the release notes generator config and you forgot to change it too:

You can set it top level according to the doc:
https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugin-options-configuration

brtbrt added 2 commits July 16, 2026 14:18

fix(release): upgrade @semantic-release/commit-analyzer to v10 for br…

e47fc9d

…eaking change support The ! notation for breaking changes (e.g., feat(scope)!:) requires conventional-commits-parser@3.3.0+. Commit-analyzer v10 includes this. Fixes #1657

Copilot AI review requested due to automatic review settings July 16, 2026 12:24

brtbrt requested a review from a team as a code owner July 16, 2026 12:24

Copilot started reviewing on behalf of brtbrt July 16, 2026 12:24 View session

Copilot AI reviewed Jul 16, 2026

View reviewed changes

Comment thread package.json

Comment on lines 81 to 83

"@semantic-release/changelog": "^6.0.1",

"@semantic-release/commit-analyzer": "^10.0.0",

"@semantic-release/git": "^10.0.1",

Comment thread .github/workflows/release.yml Outdated

brtbrt had a problem deploying to production July 16, 2026 12:55 — with GitHub Actions Error

brtbrt requested a deployment to production July 16, 2026 13:13 — with GitHub Actions Waiting

brtbrt force-pushed the mbertamini/1657-major-semantic-fix branch from bfe6119 to 70e8060 Compare July 16, 2026 13:17

brtbrt requested a deployment to production July 16, 2026 13:20 — with GitHub Actions Waiting

docs(ci): clarify breaking changes must use footer, not ! notation

f5f7d01

Add explicit note that the ! notation is not supported by semantic-release in the current configuration. Breaking changes must use the BREAKING CHANGE: footer in the commit body instead. See #1657

brtbrt force-pushed the mbertamini/1657-major-semantic-fix branch from 70e8060 to f5f7d01 Compare July 16, 2026 13:36

brtbrt added 3 commits July 16, 2026 15:41

chore(ci): explicitly reject ! notation in PR titles

5bdc35e

Add a validation step that rejects any PR title containing the ! character, since the ! notation for breaking changes is not supported by semantic-release.

docs: add TODOs for re-enabling ! notation support

816b042

Link to issue #1660 which tracks upstream semantic-release issues blocking ! notation support. When those are resolved, these TODOs should be addressed to re-enable the shorter breaking change syntax.

brtbrt changed the title ~~fix(release): recognize breaking changes with ! notation + add dry-run validation~~ fix(release): disallow breaking changes with ! notation on PRs + add dry-run validation when validating Jul 16, 2026

brtbrt added 2 commits July 16, 2026 17:41

chore(deps): update yarn cache for commit-analyzer upgrade

aedba08

brtbrt requested a deployment to production July 16, 2026 15:49 — with GitHub Actions Waiting

brtbrt requested a deployment to production July 16, 2026 15:59 — with GitHub Actions Waiting

brtbrt requested a deployment to production July 16, 2026 16:03 — with GitHub Actions Waiting

chore(ci): temporarily allow ! notation in PR titles for testing

4b0cc14

Disable the ! notation guard to test if semantic-release properly detects breaking changes with the new configuration.

brtbrt force-pushed the mbertamini/1657-major-semantic-fix branch from 5e2f331 to 4b0cc14 Compare July 16, 2026 16:12

brtbrt changed the title ~~fix(release): disallow breaking changes with ! notation on PRs + add dry-run validation when validating~~ feat(release)!: enable ! notation for breaking changes in semantic-release Jul 16, 2026

brtbrt requested a deployment to production July 16, 2026 18:29 — with GitHub Actions Waiting

brtbrt requested a deployment to production July 16, 2026 18:34 — with GitHub Actions Waiting

brtbrt force-pushed the mbertamini/1657-major-semantic-fix branch 2 times, most recently from 5a093b4 to 4b0cc14 Compare July 16, 2026 18:59

brtbrt requested a deployment to production July 16, 2026 19:01 — with GitHub Actions Waiting

brtbrt requested a deployment to production July 16, 2026 19:05 — with GitHub Actions Waiting

fix(release): require approval for validate job to protect secrets

3091e5a

brtbrt temporarily deployed to production July 16, 2026 19:06 — with GitHub Actions Inactive

brtbrt requested a deployment to production July 16, 2026 19:09 — with GitHub Actions Waiting

fix(release)!: remove explicit releaseRules configuration now that se…

fc68eb3

…mantic-release supports ! notation

brtbrt temporarily deployed to production July 16, 2026 19:20 — with GitHub Actions Inactive

brtbrt requested a deployment to production July 16, 2026 19:22 — with GitHub Actions Waiting

chore(ci): add test branch to semantic-release branches for validation

9cc2927

brtbrt temporarily deployed to production July 16, 2026 19:23 — with GitHub Actions Inactive

brtbrt requested a deployment to production July 16, 2026 19:25 — with GitHub Actions Waiting

brtbrt temporarily deployed to production July 16, 2026 19:28 — with GitHub Actions Inactive

brtbrt requested a deployment to production July 16, 2026 19:31 — with GitHub Actions Waiting

brtbrt added 5 commits July 16, 2026 23:47

fix(release): remove explicit releaseRules configuration now that sem…

b661326

…antic-release supports ! notation

remove release for extra branches than master

cf049ee

chore(deps): remove @semantic-release/commit-analyzer resolution to a…

de43cfc

…llow caret updates

chore(deps): remove @semantic-release/commit-analyzer from devDepende…

41a5691

…ncies

chore: regenerate yarn.lock after removing commit-analyzer dependency

6cb41d4

brtbrt requested a review from Marcosld July 18, 2026 14:01

ci(release): add skipValidation input to bypass dry-run step

9d602a8

Marcosld requested changes Jul 21, 2026

View reviewed changes

brtbrt added 2 commits July 21, 2026 15:41

simplify release workflow into multi-step in place of multi-jobs

3225ff1

simplify release workflow into multi-step in place of multi-jobs

a18db05

brtbrt requested a review from Marcosld July 21, 2026 14:00

Marcosld requested changes Aug 3, 2026

View reviewed changes

Uh oh!

Conversation

brtbrt commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

The whys

Changes

Core Fix

Testing & Verification!

Related Issues

Migration

Testing

Uh oh!

github-actions Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

github-actions Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Marcosld commented Jul 16, 2026

Uh oh!

github-actions Bot commented Jul 16, 2026

Uh oh!

brtbrt commented Jul 16, 2026

Update: Custom releaseRules Configuration

Why this is needed

What was added

Uh oh!

brtbrt commented Jul 16, 2026

Uh oh!

Marcosld Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

brtbrt Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Marcosld Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

brtbrt Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Marcosld Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Marcosld Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

brtbrt Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Marcosld Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brtbrt commented Jul 16, 2026 •

edited

Loading

github-actions Bot commented Jul 16, 2026 •

edited

Loading

github-actions Bot commented Jul 16, 2026 •

edited

Loading

brtbrt Jul 21, 2026 •

edited

Loading