releaseRules overriding if is a major version

[tiagoporto]

The following scenario is not working properly

Version
semantic-release@24.2.7

Config

//.releaserc.mjs

const config = {
  branches: ['main'],
  preset: 'conventionalcommits',
  plugins: [
    [
      '@semantic-release/commit-analyzer',
      {
        releaseRules: [
          {
            type: 'docs',
            release: 'minor',
          },
          {
            type: 'refactor',
            release: 'minor',
          },
        ],
      },
    ],
    '@semantic-release/release-notes-generator',
    '@semantic-release/github',
  ],
}

export default config

Example

Current version: 1.0.0

Commit list

• refactor!: rewrite algorithm
• refactor: refactor init function
• docs: update usage section

Expecting result

Next Release: 2.0.0

Release notes, something like:

### ⚠ BREAKING CHANGES

    * rewrite algorithm

### Code Refactoring

    * rewrite algorithm (a2a7ff1)
    * refactor init function (a2a4rf1)

### Documentation
    * update usage section (a23erf1)

Current result

Next Release: 1.1.0

Release notes, something like:

### ⚠ BREAKING CHANGES

    * rewrite algorithm

### Code Refactoring

    * rewrite algorithm (a2a7ff1)

Sum-up

The major version is being overridden by releaseRules

{
  type: "refactor",
  release: "minor"
}

Commits of type docs and refactor are being ignored in the release notes unless they are a breaking change.

[travi]

you've only customized your rules for the commit-analyzer, which has the responsibility of determining how to bump the version number based on the commit messages. you also need to customize the config for the release-notes-plugin if you are wanting to adjust how release notes are formatted because that is the responsibility of that plugin

[tiagoporto]

Thanks, @travi.
I'll take a look, but the most important issue now is the major version being overridden by the releaseRules.

[travi]

keep in mind that semantic-release does not define the base conventions, we only make them available for use with the automation that semantic-release provides. i'm somewhat wondering if the complication is more related to the way the underlying preset handles this than what semantic-release does on top.

the simplest way to resolve this would be to use the preset as intended where refactor and docs types do not result in a release. the preset is defined that way to limit releases to changes that actually impact the behaviors used by library consumers. for example, by definition, a refactor should be a change that changes the structure of the code without changing the behavior of the code, so it should not impact your consumer. could you explain the reasons behind why you want to deviate from the intended definition of the preset? that could help understand what options exist that could be pursued

[tiagoporto]

I like to generate a release for huge refactoring.

But maybe, it's not the point, the issue itself is part of semantic-release because is already a feature provided (releaseRules). If the semantic-release should enforce the conventions, as you are saying, I think the feature should be removed.

Let me try to explain.

The documentation shows an example with the refactor:
https://github.com/semantic-release/commit-analyzer?tab=readme-ov-file#rules-definition

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "angular",
        "releaseRules": [
          { "type": "docs", "scope": "README", "release": "patch" },
          { "type": "refactor", "scope": "core-*", "release": "minor" },
          { "type": "refactor", "release": "patch" },
          { "scope": "no-release", "release": false }
        ]
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

After, explain the case of matching rules
https://github.com/semantic-release/commit-analyzer?tab=readme-ov-file#rules-matching

Rules matching
Each commit will be compared with each rule and when it matches, the commit will be associated with the release type in the rule's release property. If a commit match multiple rules, the highest release type (major > minor > patch) is associated with the commit.

Following the convention, any breaking change should generate a major version.
https://www.conventionalcommits.org/en/v1.0.0/#summary

3. BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, 
   or appends a ! after the type/scope, introduces a breaking API 
   change (correlating with [MAJOR](http://semver.org/#summary) in Semantic Versioning).
+   A BREAKING CHANGE can be part of commits of any type.

After reading all the docs, I was expecting a refactor commit flagged as a breaking change to override the releaseRules config. Because major (breaking) > minor (releaseRules).

Do you agree with that?

[travi]

I like to generate a release for huge refactoring.

if you expect a refactor to create a user impactful change, is it still a refactor? why not just release it as a fix or a feat instead of a refactor?

If the semantic-release should enforce the conventions, as you are saying, I think the feature should be removed.

i'm not suggesting that semantic-release should enforce the conventions without tweaks, but i am trying to understand the motivations for your deviations. we are volunteer maintainers and investing work to meet the expectations of various approaches pulls from our limited pool of investable time and attention. if there is a path to accomplishing your goal with no or minimal investment, that would be preferred, so my questions are seeking those sorts of options.

semantic-release is called "semantic" because it encourages making commits that describe what the change is, not how it should be released. i'm mainly wondering if your expectations for describing what a change is might be able to align more closely with the original intent of the convention youve chosen

[santosr2]

I'm encountering the same issue; it seems the releaseRules overwrite the default indeed.

My current scenario:

Commit Analyzer setup:

"@semantic-release/commit-analyzer",
    {
      preset: "conventionalcommits",
      releaseRules: [
        { type: feature, release: minor },
        { type: chore, release: patch }
      ]
    }

My commit message:

feature!: ...

BREAKING CHANGE: ...

The documentation states "If a commit doesn't match any rule in releaseRules it will be evaluated against the default release rules", since the most crucial part is the ! and the BREAKING CHANGE: I expected it to generate a major version, but it generated a minor version instead.