Automated Release Notes Generation

Automated Release Notes Generation

Automated release notes save time and ensure consistency, but they require a disciplined commit message practice and thoughtful configuration.

Prerequisites

1. Conventional Commits format for all commit messages
2. Consistent PR titles (often enforced via CI checks)
3. Labels on PRs for categorization (feature, bugfix, breaking, etc.)

Tool Comparison

Tool	Input	Output	Versioning
semantic-release	Git commits	GitHub Release + CHANGELOG	Automatic
standard-version	Git commits	CHANGELOG.md	Automatic
conventional-changelog	Git commits	CHANGELOG.md	Manual
GitHub Auto-generated	Merged PRs	Release notes	Manual
Release Drafter	PR labels	Draft release	Manual

GitHub Actions Example

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - 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 }}

Release Drafter Configuration

# .github/release-drafter.yml
categories:
  - title: "Features"
    labels: ["feature", "enhancement"]
  - title: "Bug Fixes"
    labels: ["fix", "bugfix"]
  - title: "Breaking Changes"
    labels: ["breaking"]
  - title: "Security"
    labels: ["security"]
template: |
  ## What's Changed
  $CHANGES
  ## Contributors
  $CONTRIBUTORS

Hybrid Approach: Automate + Curate

The best release notes combine automation with manual curation:

1. Auto-generate the initial draft from commits/PRs
2. Edit highlights — add a human-written summary at the top
3. Reorder entries by importance, not chronological order
4. Add context — link to blog posts, docs, or RFCs for major features
5. Review for tone — write for users, not developers

Common Pitfalls

• Relying solely on commit messages (too terse for users)
• Including internal refactoring commits that mean nothing to users
• Not reviewing auto-generated notes before publishing
• Missing breaking changes because they were not properly tagged