diff options
Diffstat (limited to 'doc/CONTRIBUTING.md')
| -rw-r--r-- | doc/CONTRIBUTING.md | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index f41d90e..ae8c35a 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -340,3 +340,36 @@ For tests that only need synth or tracker (not both), you can still call `synth_ These are performance-critical APIs and should be called directly, not wrapped by AudioEngine. +### Script Maintenance After Hierarchy Changes + +After any major source hierarchy change (moving, renaming, or reorganizing files), you **must** review and update all scripts in the `scripts/` directory to ensure they remain functional. + +**When to perform this review:** +- Moving source files to new directories (e.g., `src/platform.cc` → `src/platform/platform.cc`) +- Renaming source files or directories +- Reorganizing the build system (CMake changes, new subdirectories) +- Changing asset locations or formats + +**Scripts that commonly require updates:** +- `scripts/check_all.sh` - Build verification and testing +- `scripts/gen_coverage_report.sh` - Code coverage analysis +- `scripts/build_win.sh` - Windows cross-compilation +- `scripts/gen_assets.sh` - Asset generation pipeline +- Any scripts with hardcoded paths or assumptions about file locations + +**Verification steps:** +1. Run `./scripts/check_all.sh` to verify builds and tests still work +2. Run `./scripts/gen_coverage_report.sh` to ensure coverage tracking handles new paths +3. Test platform-specific scripts if applicable (`build_win.sh`, `run_win.sh`) +4. Check for error messages about missing files or incorrect paths +5. Update documentation if script behavior has changed + +**Recent example:** +When `src/platform.cc` was moved to `src/platform/platform.cc`, the coverage script (`gen_coverage_report.sh`) initially failed with "unable to open /Users/skal/demo/src/platform.cc" due to stale coverage data. The fix required: +- Adding 'source' to `LCOV_OPTS` ignore list to handle missing source files +- Enabling automatic cleanup of the `build_coverage/` directory before each run +- Testing the script to verify it handles the new file structure + +**Automation:** +The `./scripts/check_all.sh` script is designed to catch most issues automatically. Always run it before committing hierarchy changes to ensure no regressions in build or test infrastructure. + |