Changelog Automation¶

Purpose¶

Strategies for automatically generating changelogs from git commits, pull requests, and release notes.

Changelog Formats¶

Keep a Changelog (Recommended)¶

Following https://keepachangelog.com/ format:

# Changelog

All notable changes to AudioLab will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New SIMD-optimized buffer operations

### Changed
- Improved parameter smoothing algorithm

### Deprecated
- Old `AudioBuffer::getData()` method (use `getChannelData()`)

### Removed
- Legacy XML state serialization

### Fixed
- Audio glitches when changing sample rate

### Security
- Fixed buffer overflow in FFT implementation

## [2.0.0] - 2025-01-15

### Added
- Real-time safety validators
- Lock-free parameter system
- Cross-platform SIMD abstraction

### Breaking Changes
- Renamed `process()` to `processBlock()` for clarity
- Changed parameter IDs to use snake_case

## [1.0.0] - 2024-12-01

Initial release

Semantic Versioning¶

MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Examples:
1.0.0 → 1.0.1 (bug fix)
1.0.1 → 1.1.0 (new feature)
1.1.0 → 2.0.0 (breaking change)

Commit Message Convention¶

Conventional Commits¶

Following https://www.conventionalcommits.org/

<type>(<scope>): <subject>

<body>

<footer>

Types¶

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style (formatting, no logic change)
refactor: Code refactoring
perf: Performance improvement
test: Adding/updating tests
chore: Build process, tooling

Scopes (Optional)¶

core: Core framework
dsp: DSP modules
ui: User interface
build: Build system
ci: CI/CD

Examples¶

feat(dsp): add SIMD-optimized lowpass filter

Implemented SSE2 and AVX versions with automatic CPU detection.
Performance improved by 4.2x on modern CPUs.

Closes #123

---

fix(core): prevent audio glitches during parameter changes

Changed parameter smoothing to use exponential ramp instead of linear.

Fixes #456

---

docs(api): improve AudioBuffer documentation

Added code examples and performance notes.
Clarified thread-safety guarantees.

---

feat(core)!: rename process() to processBlock()

BREAKING CHANGE: All audio processors must rename process() method
to processBlock() for consistency with industry standards.

Migration guide: docs/migration-v2.md

Automation Tools¶

1. standard-version (JavaScript/Node)¶

Install:

npm install --save-dev standard-version

Usage:

# First release
npm run release -- --first-release

# Patch release (1.0.0 → 1.0.1)
npm run release -- --release-as patch

# Minor release (1.0.1 → 1.1.0)
npm run release -- --release-as minor

# Major release (1.1.0 → 2.0.0)
npm run release -- --release-as major

package.json:

{
  "scripts": {
    "release": "standard-version"
  },
  "standard-version": {
    "types": [
      {"type": "feat", "section": "Features"},
      {"type": "fix", "section": "Bug Fixes"},
      {"type": "perf", "section": "Performance"},
      {"type": "docs", "section": "Documentation", "hidden": false},
      {"type": "style", "hidden": true},
      {"type": "refactor", "hidden": true},
      {"type": "test", "hidden": true},
      {"type": "chore", "hidden": true}
    ]
  }
}

2. git-cliff (Rust, Fast)¶

Install:

cargo install git-cliff
# Or: winget install git-cliff

Configuration: cliff.toml

[changelog]
header = """
# Changelog\n
All notable changes will be documented in this file.\n
"""
body = """
{% if version %}\
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
    ## [Unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\n
"""

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Features"},
    { message = "^fix", group = "Bug Fixes"},
    { message = "^doc", group = "Documentation"},
    { message = "^perf", group = "Performance"},
    { message = "^refactor", group = "Refactoring"},
    { message = "^style", skip = true},
    { message = "^test", skip = true},
    { message = "^chore", skip = true},
]

Usage:

# Generate changelog for unreleased commits
git cliff --unreleased

# Generate for specific version
git cliff --tag v2.0.0

# Update CHANGELOG.md
git cliff --output CHANGELOG.md

# Generate for current tag
git cliff --current

3. PowerShell Script (Custom)¶

generate-changelog.ps1:

param(
    [Parameter(Mandatory=$false)]
    [string]$From = "",

    [Parameter(Mandatory=$false)]
    [string]$To = "HEAD"
)

# Get commits
$Commits = if ($From) {
    git log "$From..$To" --pretty=format:"%H|%s|%an|%ad" --date=short
} else {
    git log $To --pretty=format:"%H|%s|%an|%ad" --date=short
}

# Group by type
$Features = @()
$Fixes = @()
$Docs = @()
$Others = @()

foreach ($Line in $Commits) {
    $Parts = $Line -split '\|'
    $Message = $Parts[1]

    if ($Message -match '^feat') {
        $Features += $Message -replace '^feat(\(.+?\))?: ', ''
    }
    elseif ($Message -match '^fix') {
        $Fixes += $Message -replace '^fix(\(.+?\))?: ', ''
    }
    elseif ($Message -match '^docs') {
        $Docs += $Message -replace '^docs(\(.+?\))?: ', ''
    }
    else {
        $Others += $Message
    }
}

# Generate changelog
Write-Host "## [Unreleased] - $(Get-Date -Format 'yyyy-MM-dd')"
Write-Host ""

if ($Features.Count -gt 0) {
    Write-Host "### Added"
    foreach ($F in $Features) {
        Write-Host "- $F"
    }
    Write-Host ""
}

if ($Fixes.Count -gt 0) {
    Write-Host "### Fixed"
    foreach ($F in $Fixes) {
        Write-Host "- $F"
    }
    Write-Host ""
}

if ($Docs.Count -gt 0) {
    Write-Host "### Documentation"
    foreach ($D in $Docs) {
        Write-Host "- $D"
    }
    Write-Host ""
}

GitHub Release Notes¶

Automatic Release Notes¶

GitHub can generate release notes automatically:

Go to Releases → Draft a new release
Click "Generate release notes"
Edit and publish

Release Template¶

.github/RELEASE_TEMPLATE.md:

## What's Changed

<!-- Auto-generated PR list -->

## New Features
- Feature 1
- Feature 2

## Bug Fixes
- Fix 1
- Fix 2

## Breaking Changes
⚠️ This release contains breaking changes:
- Change 1 (migration guide: link)

## Installation

### Windows
```bash
winget install audiolab

macOS¶

brew install audiolab

Linux¶

# See installation docs

Full Changelog¶

v1.0.0...v2.0.0

## CI/CD Integration

### GitHub Actions

**`.github/workflows/release.yml`:**
```yaml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Generate Changelog
        id: changelog
        run: |
          # Using git-cliff
          cargo install git-cliff
          git cliff --latest --strip all > RELEASE_NOTES.md

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: RELEASE_NOTES.md
          draft: false
          prerelease: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Best Practices¶

Commit Message Guidelines¶

# ✅ GOOD
feat(dsp): add butterworth filter implementation
fix(core): resolve audio glitch on buffer resize
docs(api): improve parameter documentation

# ❌ BAD
added stuff
fix bug
update

Changelog Entry Guidelines¶

# ✅ GOOD - Specific, actionable
- Added SIMD-optimized FFT (4.2x faster)
- Fixed audio glitch when changing sample rate above 96kHz
- Improved parameter smoothing to prevent clicks

# ❌ BAD - Vague
- Performance improvements
- Bug fixes
- Updates

Versioning Strategy¶

v1.0.0: Initial stable release
v1.1.0: Add new features (backward compatible)
v1.2.0: More features
v2.0.0: Breaking changes (rename APIs, remove deprecated)

Tools Comparison¶

Tool	Language	Speed	Features	Best For
standard-version	JavaScript	Medium	Auto-versioning, tagging	JS projects
git-cliff	Rust	Fast	Highly customizable	Any project
release-please	TypeScript	Medium	Google-style, auto-PR	GitHub
Custom Script	PowerShell	Fast	Full control	Windows-first

References¶

Keep a Changelog: https://keepachangelog.com/
Conventional Commits: https://www.conventionalcommits.org/
Semantic Versioning: https://semver.org/
git-cliff: https://github.com/orhun/git-cliff
standard-version: https://github.com/conventional-changelog/standard-version