Semantic Versioning for AudioLab

Overview

AudioLab follows Semantic Versioning 2.0.0 to communicate the nature of changes to users and developers clearly.

Version Format

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:
1.0.0         - First stable release
1.2.3         - Standard release
2.0.0-alpha.1 - Pre-release
2.0.0-beta.2  - Beta release
2.0.0-rc.1    - Release candidate
1.2.3+20231015.a3f8b92 - With build metadata

Component Definitions

MAJOR Version (Breaking Changes)

Increment when making incompatible API changes that break backward compatibility.

Examples for AudioLab: - Changed audio buffer API signature - Removed deprecated public functions - Changed preset file format (non-backward compatible) - Changed plugin parameter IDs (breaks DAW automation) - Changed minimum system requirements (OS, CPU features)

Migration Impact: - Users may need to update DAW projects - Presets may require migration tool - Automation data may need remapping - Code using AudioLab libraries must be updated

Communication: - MUST provide migration guide - MUST document all breaking changes - SHOULD provide migration tools when feasible - Consider deprecation period before breaking change

---

MINOR Version (New Features)

Increment when adding new functionality in a backward-compatible manner.

Examples for AudioLab: - Added new effect algorithm (reverb, compressor, etc.) - Added new parameter to existing effect (without changing existing params) - Added new export format support - Added new preset management features - Added new UI controls (without removing old ones) - Improved performance of existing features

Migration Impact: - Zero breaking changes - Existing projects work unchanged - Users can opt-in to new features - No code changes required for existing integrations

Communication: - Document new features in release notes - Provide usage examples - Update user manual

---

PATCH Version (Bug Fixes)

Increment when making backward-compatible bug fixes.

Examples for AudioLab: - Fixed audio clicks on bypass - Fixed memory leak in reverb tail - Fixed UI rendering glitch - Fixed preset loading edge case - Fixed buffer overflow vulnerability - Improved numerical stability

Migration Impact: - Zero API changes - Transparent to users (should just work better) - May fix bugs some code was relying on (rare)

Communication: - List fixed issues in changelog - Reference issue tracker numbers

---

Pre-release Versions

Use for versions not yet ready for production.

Format

MAJOR.MINOR.PATCH-IDENTIFIER.NUMBER

Where IDENTIFIER is:
- alpha   : Early development, unstable
- beta    : Feature complete, stabilizing
- rc      : Release candidate, final testing

Examples with Lifecycle

2.0.0-alpha.1   → Initial development
2.0.0-alpha.2   → Adding features
2.0.0-alpha.3   → More features
2.0.0-beta.1    → Feature freeze, bug fixing
2.0.0-beta.2    → More bug fixes
2.0.0-rc.1      → Final testing
2.0.0-rc.2      → Last minute fixes
2.0.0           → Stable release!

Stability Expectations

Phase	Stability	Purpose	Who Uses
alpha	Unstable	Feature development	Internal devs
beta	Semi-stable	Feature testing	Beta testers
rc	Stable	Final validation	QA team, early adopters
(none)	Production	Public use	All users

---

Build Metadata

Optional metadata appended with + (does NOT affect version precedence).

1.2.3+20231015           # Date
1.2.3+a3f8b92           # Git commit hash
1.2.3+20231015.a3f8b92  # Date + commit
1.2.3+exp.sha.5114f85   # Experimental build

Use Cases: - Nightly builds: 1.2.3+nightly.20231015 - CI builds: 1.2.3+ci.456 - Debug builds: 1.2.3+debug

---

Version Ordering

Precedence determined by comparing identifiers from left to right:

1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-beta.2
< 1.0.0-rc.1 < 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0

Key Rule: Pre-release versions have LOWER precedence than release versions.

---

Decision Tree

Use this flowchart to determine version bump:

                    Did API change?
                          │
          ┌───────────────┴───────────────┐
          │                               │
         YES                             NO
          │                               │
    Is it compatible?                    │
          │                               │
    ┌─────┴─────┐                        │
   NO          YES                       │
    │           │                        │
MAJOR++      MINOR++                     │
  RESET        RESET                     │
  MINOR        PATCH                     │
  RESET                               PATCH++
  PATCH

Examples:
- Changed buffer API → MAJOR
- Added reverb effect → MINOR
- Fixed crash bug → PATCH

---

Special Cases

Version 0.x.y (Initial Development)

0.1.0   - First working prototype
0.2.0   - Added basic features
0.9.0   - Feature complete, stabilizing
1.0.0   - First stable public release

Semantics during 0.x: - 0.x.0 → MINOR changes may break compatibility - 0.x.y → PATCH changes should be compatible - Anything may change at any time - Public API not considered stable

Transition to 1.0.0: When you're ready to declare a stable API and commit to backward compatibility.

---

Dependency Compatibility

AudioLab dependencies should use compatible version ranges:

{
  "dependencies": {
    "juce": "^7.0.0",      // Compatible with 7.x.x
    "catch2": "~3.4.0",    // Compatible with 3.4.x only
    "eigen3": ">=3.4.0"    // Any version >= 3.4.0
  }
}

Operators: - ^ (caret): Compatible MINOR/PATCH updates - ~ (tilde): Compatible PATCH updates only - >=: Minimum version - =: Exact version (avoid if possible)

---

Real-World Examples

Example 1: Bug Fix Release

Current: 1.2.3
Fix: Reverb tail was cutting off early

Decision: PATCH (bug fix, no API change)
New version: 1.2.4

Example 2: New Feature

Current: 1.2.4
Change: Added sidechain compression feature

Decision: MINOR (new feature, backward compatible)
New version: 1.3.0
Note: PATCH reset to 0

Example 3: Breaking Change

Current: 1.3.2
Change: Changed AudioBuffer API from pointers to references

Decision: MAJOR (API incompatible)
New version: 2.0.0
Note: MINOR and PATCH reset to 0

Example 4: Pre-release Cycle

Current: 1.9.5 (stable)
Plan: Major refactor for v2.0

Cycle:
1. Start development → 2.0.0-alpha.1
2. Add features      → 2.0.0-alpha.2, alpha.3...
3. Feature freeze    → 2.0.0-beta.1
4. Bug fixes         → 2.0.0-beta.2, beta.3...
5. Final testing     → 2.0.0-rc.1
6. Fix critical bug  → 2.0.0-rc.2
7. Release!          → 2.0.0

---

Anti-Patterns (Don't Do This)

❌ Marketing-Driven Versioning

❌ "Let's go from 1.5 to 3.0 because it sounds cooler"
✅ Follow SemVer rules regardless of marketing

❌ Skipping Numbers

❌ 1.2.3 → 1.2.5 (skipped 1.2.4)
✅ Sequential increments only

❌ Using PATCH for Features

❌ 1.2.3 → 1.2.4 (added new reverb algorithm)
✅ 1.2.3 → 1.3.0 (new feature = MINOR bump)

❌ Breaking Compatibility in MINOR/PATCH

❌ 1.2.3 → 1.3.0 (removed deprecated function)
✅ 1.2.3 → 2.0.0 (breaking = MAJOR bump)

---

Version vs. Release

Important Distinction:

• Version: The semantic identifier (1.2.3)
• Release: The distribution package (AudioLab-1.2.3-Setup.exe)

One version may have multiple releases: - AudioLab-1.2.3-Setup-Windows-x64.exe - AudioLab-1.2.3-Setup-macOS-arm64.dmg - AudioLab-1.2.3-VST3-Linux.tar.gz

---

Checklist: Version Decision

Before bumping version, verify:

• Analyzed all changes since last release
• Identified most significant change type
• Checked for breaking changes (MAJOR)
• Checked for new features (MINOR)
• Checked for bug fixes only (PATCH)
• Updated CHANGELOG.md with accurate categories
• Version bump matches change significance
• Migration guide prepared (if MAJOR)
• All version locations will be updated (see version_locations.md)

---

References

• Semantic Versioning 2.0.0
• Keep a Changelog
• Conventional Commits

---

Remember: Semantic Versioning is a contract with your users. Breaking it breaks trust.