Skip to content

05_17_02: Commit Conventions - AudioLab Conventional Commits

Executive Summary

The AudioLab Commit Conventions implement Conventional Commits 1.0.0 with AudioLab-specific extensions for audio development. This system provides standardized commit messages that enable automated versioning, changelog generation, and clear communication history.

Key Features: - Conventional Commits 1.0.0 compliance - AudioLab-specific scopes (DSP, UI, architecture layers) - Automated validation via Git hooks - Commit message templates - Changelog automation - Version bump detection

Format

Basic Structure

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

[optional body]

[optional footer]

Examples

Minimal: 

feat(dsp): add reverb engine

Standard: 

feat(dsp): add reverb engine

Implements plate reverb algorithm with early reflections
and late reverberation tail.

Complete: 

feat(dsp): add reverb engine

Implements plate reverb algorithm with early reflections
and late reverberation tail. Uses Schroeder allpass filters
for diffusion and comb filters for late reverb.

Performance: 2.3% CPU @ 48kHz, Memory: 2.4 MB
Audio Quality: SNR 96dB, THD+N < 0.001%

BREAKING CHANGE: Changes preset format v1 to v2

Implements: AL-123
Reviewed-by: @dsp-team

Commit Types

feat (Feature)

New feature or functionality

Triggers: - MINOR version bump - Changelog entry - Documentation update

Requirements: - Tests included - Documentation updated

Examples: 

feat(dsp): add compressor engine
feat(ui): implement preset browser
feat(api): add MIDI learn capability

fix (Bug Fix)

Bug fix

Triggers: - PATCH version bump - Changelog entry

Requirements: - Regression test included - Bug report reference

Examples: 

fix(dsp): resolve audio glitch at buffer boundaries
fix(ui): correct knob sensitivity
fix(build): resolve Windows compilation error

perf (Performance)

Performance improvement

Triggers: - PATCH version bump - Performance benchmark update - Changelog entry

Requirements: - Benchmark results included - Performance metrics documented

Examples: 

perf(dsp): optimize FFT using SIMD
perf(ui): reduce repaint overhead
perf(memory): reduce allocation frequency

refactor

Code refactoring (no behavior change)

Triggers: - No version bump - Code review required

Requirements: - All tests still pass - No API changes - Documentation updated if needed

Examples: 

refactor(dsp): extract filter design to separate class
refactor(ui): simplify component hierarchy

test

Add or update tests

Examples: 

test(dsp): add unit tests for filter coefficients
test(integration): add end-to-end preset loading test

docs

Documentation only

Examples: 

docs(api): update parameter documentation
docs(tutorial): add getting started guide

style

Code style changes (formatting, whitespace)

Requirements: - No functional changes

Examples: 

style(core): apply clang-format
style(ui): fix indentation

build

Build system or dependencies

Examples: 

build(cmake): update JUCE to 7.0.5
build(vcpkg): add Catch2 dependency

ci

CI/CD configuration

Examples: 

ci(github): add macOS M1 build job
ci(azure): update test pipeline

chore

Maintenance tasks

Examples: 

chore(deps): update dev dependencies
chore(config): update .gitignore

revert

Revert previous commit

Format: 

revert: <header of reverted commit>

Requirements: - Include SHA of reverted commit - Explain reason for revert

Scopes

Core DSP

  • dsp: Digital signal processing core
  • filters: Filter algorithms
  • oscillators: Oscillator implementations
  • effects: Audio effects
  • dynamics: Dynamics processing
  • modulation: Modulation systems
  • analysis: Analysis tools

Architecture Layers

  • kernels: L0 - Atomic operations
  • atoms: L1 - Basic processing blocks
  • cells: L2 - Complex components
  • engines: L3 - Complete processors

UI

  • ui: User interface
  • components: UI components
  • layout: Layout management
  • graphics: Graphics rendering
  • interaction: User interaction
  • theming: Theme system

System

  • api: Public API
  • core: Core system functionality
  • build: Build system
  • tests: Test infrastructure
  • docs: Documentation
  • config: Configuration files

Platform

  • platform: Platform-specific code
  • windows: Windows platform
  • macos: macOS platform
  • linux: Linux platform
  • ios: iOS platform
  • android: Android platform

Plugin Formats

  • vst3: VST3 plugin format
  • au: Audio Units format
  • aax: AAX plugin format
  • clap: CLAP plugin format

Infrastructure

  • ci: Continuous integration
  • deploy: Deployment
  • security: Security-related changes

Subject Line Rules

Length

  • Minimum: 10 characters
  • Maximum: 72 characters

Case

  • Use lowercase
  • No capitalization

Format

  • Use imperative mood: "add", "fix", "update"
  • NOT past tense: "added", "fixed", "updated"
  • No period at end
  • Be specific and descriptive

Good Examples

✅ add reverb engine with early reflections ✅ fix audio glitch at buffer boundaries ✅ optimize FFT using AVX2 instructions ✅ update preset format to v2

Bad Examples

❌ Added feature (past tense) ❌ Fix bug. (period at end) ❌ Fixed it (not descriptive) ❌ WIP (not meaningful) ❌ Update (too vague)

Body

Format

  • Wrap at 72 characters
  • Blank line after subject
  • Explain what and why (not how)
  • Provide context
  • Reference related issues
  • Document breaking changes
  • Include performance impact
  • Include audio quality metrics

Sections

  • Motivation: Why this change is needed
  • Implementation: High-level implementation notes
  • Performance: Performance characteristics
  • Audio Quality: Audio quality metrics
  • Testing: How it was tested
  • Migration: Migration guide for breaking changes

Keywords

BREAKING CHANGE

BREAKING CHANGE: <description>

Triggers: - MAJOR version bump - Migration guide required

Examples: 

BREAKING CHANGE: Preset format changed from v1 to v2
BREAKING CHANGE: API signature changed for process()

Implements

Implements: <issue-id>

Examples: 

Implements: AL-123
Implements: #456

Fixes

Fixes: <issue-id>

Triggers: - Auto-close issue

Examples: 

Fixes: AL-789
Fixes: #234

Closes

Closes: <issue-id>

Refs

Refs: <issue-id>

Examples: 

Refs: AL-123, AL-456

Reviewed-by

Reviewed-by: <reviewer>

Examples: 

Reviewed-by: @dsp-team
Reviewed-by: John Doe <john@example.com>

Co-authored-by

Co-authored-by: <name> <email>

Examples: 

Co-authored-by: Jane Doe <jane@example.com>

AudioLab Extensions

Performance Markers

CPU

CPU: <percentage>% @ <sample-rate>

Examples: 

CPU: 2.3% @ 48kHz
CPU: 5.1% @ 96kHz (worst case)

Memory

Memory: <amount>

Examples: 

Memory: 2.4 MB
Memory: 128 KB (per instance)

Latency

Latency: <samples>

Examples: 

Latency: 0 samples (zero-latency)
Latency: 2048 samples (lookahead)

Audio Quality Markers

SNR

SNR: <value> dB

Examples: 

SNR: 96 dB

THD+N

THD+N: <value>%

Examples: 

THD+N: 0.001%

Frequency Range

Range: <low>-<high> Hz

Examples: 

Range: 20-20000 Hz

Complete Examples

Feature with Performance Metrics

feat(dsp): add plate reverb engine

Implements high-quality plate reverb using Schroeder topology
with 8 parallel comb filters and 4 allpass filters for diffusion.

Features:
- Early reflections simulation
- Late reverb tail with configurable decay
- Pre-delay up to 500ms
- High-frequency damping control

Performance: CPU 2.3% @ 48kHz, 4.1% @ 96kHz
Audio Quality: SNR 96dB, THD+N < 0.001%
Memory: 2.4 MB per instance

Implements: AL-123
Reviewed-by: @dsp-team

Bug Fix

fix(ui): resolve knob jump on parameter change

Knobs were jumping when parameter values changed externally
(automation, preset load, MIDI CC). Fixed by updating the
internal value smoothly instead of snapping immediately.

Root cause: Missing value smoothing in parameter callback.

Testing:
- Manual automation in DAW
- Preset loading
- MIDI CC mapping

Fixes: AL-456

Performance Optimization

perf(dsp): optimize FFT using AVX2 intrinsics

Replaced scalar FFT implementation with AVX2 SIMD version
for improved performance on modern x64 CPUs.

Before:
- CPU: 8.7% @ 48kHz (2048-point FFT)

After:
- CPU: 2.1% @ 48kHz (2048-point FFT)

Improvement: 76% reduction in CPU usage

Falls back to scalar implementation on non-AVX2 CPUs.
All audio quality tests pass.

Refs: AL-789

Breaking Change

feat(api): update preset format to v2

Redesigned preset format for better extensibility and
forward compatibility. New format uses JSON instead of
binary serialization.

Features:
- Human-readable format
- Better version control friendly
- Extensible metadata
- Backward compatibility layer

BREAKING CHANGE: Preset files use new .al2 extension

Migration guide:
1. Run preset converter: python scripts/convert_presets.py
2. Update file extensions from .al to .al2
3. Test all presets in target DAW

Implements: AL-890
Reviewed-by: @api-team, @qa-team

Installation

Install Git Hooks

# Navigate to hooks directory
cd "3 - COMPONENTS/05_MODULES/05_17_VERSION_CONTROL/05_17_02_commit_conventions/hooks"

# Install hooks
./install-hooks.sh

Install commitlint (Optional)

For enhanced validation:

# Install commitlint
npm install -g @commitlint/cli @commitlint/config-conventional

# Copy config to repo root
cp commitlint.config.js <repo-root>/.commitlintrc.js

Usage

Manual Validation

Validate a message

python commit_validator.py validate "feat(dsp): add reverb engine"

Validate from file

python commit_validator.py validate-file .git/COMMIT_EDITMSG

Check recent commits

python commit_validator.py check-repo --count 10

Using Templates

Templates are automatically applied based on branch type:

  • feature/* → feature template
  • bugfix/* → bugfix template
  • hotfix/* → bugfix template
  • refactor/* → refactor template

Manual Template Use

# View template
cat templates/feature.txt

# Use with git commit
git commit -t templates/feature.txt

Validation Rules

Enforced

  • ✅ Valid type from allowed list
  • ✅ Valid scope from allowed list
  • ✅ Subject line 10-72 characters
  • ✅ Subject lowercase
  • ✅ Subject no period at end
  • ✅ Imperative mood (not past tense)
  • ✅ No forbidden words

Warnings

  • ⚠️ Body recommended for feat/perf/refactor
  • ⚠️ Performance metrics for perf type
  • ⚠️ Issue reference for fix type

Forbidden Words

  • ❌ WIP
  • ❌ TODO
  • ❌ FIXME
  • ❌ test commit
  • ❌ temp

Changelog Generation

Commit messages automatically generate changelog:

## [2.1.0] - 2024-01-15

### Features
- **dsp**: add plate reverb engine (AL-123)
- **ui**: implement preset browser (AL-456)

### Bug Fixes
- **dsp**: resolve audio glitch at buffer boundaries (AL-789)
- **ui**: correct knob sensitivity (AL-234)

### Performance Improvements
- **dsp**: optimize FFT using AVX2 intrinsics (AL-345)

### Breaking Changes
- **api**: Preset format changed from v1 to v2
  - Migration: Run `python scripts/convert_presets.py`

Version Bumping

Commit types automatically trigger version bumps:

Commit Type Version Bump Example
feat MINOR 2.0.0 → 2.1.0
fix PATCH 2.1.0 → 2.1.1
perf PATCH 2.1.1 → 2.1.2
BREAKING CHANGE MAJOR 2.1.2 → 3.0.0
docs, style, test, chore none no change

Team-Specific Rules

DSP Team

  • Required: Performance metrics in body
  • Required: Audio quality metrics
  • Required: Review from @dsp-team

UI Team

  • Required: Screenshots for visual changes

API Team

  • Required: Breaking change documentation
  • Required: Migration guide
  • Required: Review from @api-team

Best Practices

DO ✅

  • Use imperative mood
  • Be specific and descriptive
  • Reference issues
  • Include metrics for performance changes
  • Explain why (not just what)
  • Keep commits atomic (one logical change)
  • Run validator before committing

DON'T ❌

  • Use past tense
  • Write vague subjects
  • Skip body for important changes
  • Include multiple unrelated changes
  • Use generic messages
  • Skip issue references

Troubleshooting

Hook Rejects Commit

  1. Check format: Ensure type(scope): subject format
  2. Validate type: Must be from allowed list
  3. Validate scope: Must be from allowed list
  4. Check subject: 10-72 chars, lowercase, no period
  5. Check mood: Use imperative (add, not added)
  6. Check words: No forbidden words

Template Not Applied

  1. Ensure hooks are installed: ./install-hooks.sh
  2. Check branch name format: type/scope-description
  3. Verify prepare-commit-msg hook is executable

Commitlint Not Found

Use Python fallback validator: 

python commit_validator.py validate-file .git/COMMIT_EDITMSG

Integration

With Branch Manager

Branch names auto-populate scope: 

feature/dsp-reverb → feat(dsp): ...
bugfix/ui-knobs → fix(ui): ...

With Version Manager

Commits trigger version bumps: 

# Feat commit → MINOR bump
git commit -m "feat(dsp): add reverb"
# Version: 2.0.0 → 2.1.0

# Fix commit → PATCH bump
git commit -m "fix(ui): resolve glitch"
# Version: 2.1.0 → 2.1.1

With CI/CD

  • Automated changelog generation
  • Version bump automation
  • Release notes generation

Configuration Files

  • commit_conventions.yaml: Complete conventions specification
  • commitlint.config.js: Node.js commitlint configuration
  • commit_validator.py: Python validation tool
  • templates/: Message templates
  • hooks/: Git hooks for validation

References

Part of AudioLab Version Control System (05_17_VERSION_CONTROL)