🚨 Migration Guide: Fix Empty Release Notes in conventional-changelog v10

[dcapslock]

If you recently updated dependencies or noticed that your live automated releases are suddenly generating completely empty release notes—even though npm run release -- --dry-run looks perfectly fine—you have hit a breaking architectural change introduced in conventional-changelog-conventionalcommits v10.x (which ships natively inside @semantic-release/release-notes-generator@14.1.0).

What Changed?

In v10, global configuration hoisting has been completely deprecated in favour of strict parameter isolation.

1. Global Configuration Defunct: Configuration blocks like preset, presetConfig, and releaseRules sitting at the global root of .releaserc or release.config.js files are silently ignored by the live execution engine.
2. Strict History Crawling: The underlying git client was completely rewritten. It is now highly sensitive to legacy, non-SemVer tags (e.g., raw numbers like 10 or string words like beta) anywhere in the repo's history tree, causing the live commit delta engine to crash silently.

---

How to Fix It

Step 1: Update Your .releaserc.yml Configuration

You must move all parsing and generation rules directly inside the block-scoped configuration arrays of the specific plugins that execute them.

Update your configuration layout using this explicit structure:

# ❌ DO NOT place preset, presetConfig, or releaseRules at the global root anymore!

plugins:
  - - "@semantic-release/commit-analyzer"
    - preset: conventionalcommits
      releaseRules:
        - type: feat
          release: minor
        - type: fix
          release: patch
        - type: deps
          release: patch
        # ... your custom evaluation rules go here ...

  - - "@semantic-release/release-notes-generator"
    - preset: conventionalcommits
      presetConfig:
        types:
          - type: feat
            section: ⭐ New Features
          - type: fix
            section: 🐞 Bug Fixes
          - type: deps
            section: 📦 Dependency Upgrades
          # ... your custom emoji markdown headers go here ...

  - - "@semantic-release/changelog"
    - changelogFile: CHANGELOG.md

  # ... standard downstream plugins (git, github, etc.) follow as normal ...

Step 2: Purge Legacy Non-SemVer Tags

If your local or remote repository contains ancient or untracked single-digit tags (like 3, 4, 5) or raw string tags (like beta), the new v10 engine will choke sorting the version timeline.

Run this command locally to scrub them out:

# 1. Clear invalid tags from your machine
git tag -d beta 1 2 3 4 5 6 7 8 9 10

# 2. Mirror the cleanup to GitHub remotes (if they exist there)
git push origin --delete beta 1 2 3 4 5 6 7 8 9 10 2>/dev/null || true

---

Why did Dry-Run work but Live fail?

During a --dry-run, semantic-release uses a lenient configuration-merging step in memory. However, during a live execution, it hands history evaluation over to a completely isolated @conventional-changelog/git-client runtime. This runtime only reads configurations block-scoped inside the plugin arrays. Without this explicit nesting, it falls back to defaults, fails to match your custom commit types, and yields 0 notes.

[dcapslock]

Example change for UIX - Lint-Free-Technology/uix@d8d22bf

[dcapslock]

Still seems to be an upstream issue with release notes generator. See semantic-release/release-notes-generator#992

[dcapslock]

OK. Adding overrides for conventional commits package versions gets semantic release fixed. So we can do this until semantic release notes generator is fixed.

  "overrides": {
    "@babel/core": "$@babel/core",
    "conventional-changelog-angular": "^9.0.0",
    "conventional-changelog-writer": "^9.0.0",
    "conventional-commits-filter": "^6.0.0",
    "conventional-commits-parser": "^7.0.0"
  },

Also to note that hidden: true is now effect: hidden. For chores easy to just remove chore type as chores are hidden by default.