Release Notes Generator: Conventional Commits & CHANGELOG Guide

Conventional Commits → Release Notes Mapping

Conventional Commits encode intent in the commit message. Release tools read these types and map them to version bumps and changelog sections automatically.

# Commit format: type(scope): short description
#
# BREAKING CHANGE → MAJOR bump → "Breaking Changes" section
feat!: migrate authentication to OAuth 2.0
# or with footer:
feat(auth): add OAuth 2.0 support

BREAKING CHANGE: Basic auth is no longer supported. Migrate to OAuth tokens.

# feat → MINOR bump → "Features" section
feat(api): add bulk user import endpoint
feat: support dark mode in dashboard

# fix → PATCH bump → "Bug Fixes" section
fix(auth): prevent session timeout on active use
fix: correct timezone handling in date picker

# perf → PATCH bump → "Performance Improvements" section
perf(db): add index on users.email column

# These types produce PATCH but often appear in notes:
refactor: extract validation logic to separate module
docs: add API authentication examples

# These types are typically excluded from release notes:
test: add edge case coverage for date parsing
chore: upgrade dev dependencies
ci: cache npm dependencies in GitHub Actions

semantic-release GitHub Actions Setup

semantic-release is fully automated — it runs on every merge to main, determines if a release is needed, bumps the version, updates CHANGELOG.md, creates a GitHub Release, and optionally publishes to npm. Zero manual steps after setup.

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # full history required for semantic-release
          persist-credentials: false
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}   # omit if not publishing to npm

# release.config.js
module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', { changelogFile: 'CHANGELOG.md' }],
    '@semantic-release/npm',
    ['@semantic-release/git', {
      assets: ['CHANGELOG.md', 'package.json'],
      message: 'chore(release): ${nextRelease.version} [skip ci]'
    }],
    '@semantic-release/github',
  ],
};

release-please: PR-Based Release Workflow

release-please creates a Release PR that accumulates all pending changes. You decide when to release by merging the PR — giving you control over timing while keeping the preparation work automated.

# .github/workflows/release-please.yml
name: Release Please
on:
  push:
    branches: [main]

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          release-type: node
          token: ${{ secrets.GITHUB_TOKEN }}

      # Steps below only run when the Release PR is merged (a release happens)
      - uses: actions/checkout@v4
        if: ${{ steps.release.outputs.release_created }}
      - uses: actions/setup-node@v4
        if: ${{ steps.release.outputs.release_created }}
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci && npm publish
        if: ${{ steps.release.outputs.release_created }}
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

semantic-release vs release-please Comparison