Skip to content

Bug Fixing Workflow

Overview

Standard process for identifying, reproducing, fixing, and validating bug fixes.

Process

1. Issue Reporting

  • Create GitHub issue with bug report template
  • Include reproduction steps
  • Specify affected platforms
  • Attach logs/stack traces if available
  • Label with severity (critical/high/medium/low)

2. Reproduction

# Create bug fix branch
git checkout -b fix/issue-number-short-description

Reproduce locally: - [ ] Follow reported steps - [ ] Verify on affected platform(s) - [ ] Document minimal reproduction case - [ ] Add debug logging if needed

3. Root Cause Analysis

  • Use debugger to identify failure point
  • Review recent changes (git blame, git log)
  • Check related code paths
  • Document root cause in issue comments

Common audio bug categories: - Buffer overruns/underruns - Race conditions - RT safety violations - Incorrect sample rate handling - Phase cancellation issues - Denormal performance problems

4. Fix Implementation

  • Write failing test that reproduces bug
  • Implement minimal fix
  • Verify test now passes
  • Check for similar issues in codebase
  • Follow coding standards

RT safety validation: 

#ifdef AUDIOLAB_DEBUG
    RT_ASSERT(isLockFree());
    RT_ASSERT(!allocatesMemory());
#endif

5. Testing

  • Original reproduction case fixed
  • Unit tests pass
  • No regressions in existing tests
  • Test on all affected platforms
  • Performance impact minimal

Regression testing: - Run full test suite - Check related functionality - Validate with real-world usage if possible

6. Documentation

  • Update comments explaining the fix
  • Document why the bug occurred
  • Add test case documenting the bug
  • Update docs if behavior changed

7. Review & Merge

  • Create PR linking to issue
  • Reference issue number in commit message
  • Get review approval
  • Merge and close issue

Bug Severity Guidelines

Critical

  • Audio engine crashes
  • Data loss
  • Complete feature failure
  • Timeline: Fix within 24 hours

High

  • Incorrect audio output
  • Performance degradation >20%
  • Cross-platform inconsistency
  • Timeline: Fix within 3-5 days

Medium

  • Minor artifacts
  • Edge case failures
  • Documentation errors
  • Timeline: Fix within 1-2 weeks

Low

  • Cosmetic issues
  • Non-blocking warnings
  • Performance optimization opportunities
  • Timeline: Fix when convenient

Debugging Strategies

Audio Glitches

// Log buffer info
AUDIOLAB_LOG("Buffer: size=%zu, SR=%d, pos=%zu",
             buffer.size(), sampleRate, position);

// Check for denormals
if (std::fpclassify(sample) == FP_SUBNORMAL) {
    AUDIOLAB_WARN("Denormal detected at sample %zu", i);
}

// Validate range
AUDIOLAB_ASSERT(sample >= -1.0f && sample <= 1.0f);

Race Conditions

  • Use thread sanitizer: cmake -DENABLE_TSAN=ON
  • Add memory barriers
  • Validate lock-free correctness

Performance Issues

  • Profile with platform tools (VTune, Instruments, perf)
  • Check for cache misses
  • Look for unexpected allocations

Commit Message Template

fix: resolve [brief description] (#issue-number)

Root cause: [explanation]
Solution: [what changed]

Fixes #issue-number

Best Practices

Write the Test First

Failing test → Fix → Passing test - Ensures bug is truly fixed - Prevents regressions - Documents expected behavior

Minimal Changes

  • Fix only what's necessary
  • Don't refactor while fixing (separate PR)
  • Keep changes focused and reviewable

Platform-Specific Bugs

  • Test on actual platform, not emulation
  • Check compiler-specific behavior
  • Validate threading model differences

Communication

  • Update issue with progress
  • Document findings
  • Share knowledge with team