diff options
Diffstat (limited to 'doc/CONTRIBUTING.md')
| -rw-r--r-- | doc/CONTRIBUTING.md | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 13be092..4bb894e 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -21,6 +21,41 @@ Before preparing or proposing a commit, you **must** perform the following verif Refer to the "Testing" and "Windows Cross-Compilation" sections in `HOWTO.md` for detailed instructions. +### Verify Debug Logging Compiles Before Committing + +Before any significant commit (especially those modifying audio, rendering, or asset systems), **verify that the debug logging code compiles** without errors. This ensures that the diagnostic code remains maintainable even when not actively used. + +To enable all debug logging and verify compilation: +```bash +cmake -S . -B build_debug_check -DDEMO_ENABLE_DEBUG_LOGS=ON +cmake --build build_debug_check -j4 +``` + +The build **must** succeed without errors or warnings. Debug logging is stripped from release builds but preserved for development and troubleshooting. + +#### Debug Logging Categories + +The project uses conditional debug logging macros defined in `src/util/debug.h`: +- `DEBUG_LOG_AUDIO`: Audio backend timing, callbacks, device configuration +- `DEBUG_LOG_RING_BUFFER`: Ring buffer state, underruns, bounds checks +- `DEBUG_LOG_TRACKER`: Music pattern triggers, sample caching +- `DEBUG_LOG_SYNTH`: Voice management, spectrogram registration +- `DEBUG_LOG_3D`: 3D rendering, camera, scene queries +- `DEBUG_LOG_ASSETS`: Asset loading, procedural generation +- `DEBUG_LOG_GPU`: WebGPU commands, pipeline state + +Use these macros instead of direct `fprintf(stderr, ...)` calls in new diagnostic code. + +**Example:** +```cpp +#include "util/debug.h" + +#if defined(DEBUG_LOG_AUDIO) + static int callback_count = 0; + DEBUG_AUDIO("[CALLBACK #%d] Processing %d frames\n", ++callback_count, frame_count); +#endif /* defined(DEBUG_LOG_AUDIO) */ +``` + ### Format Code Before Committing All code **must** be formatted using `clang-format` before committing. This ensures a consistent coding style across the entire codebase. |