From 8a2c465dbd17c1a96dbcab1997c5df110a26afe8 Mon Sep 17 00:00:00 2001 From: skal Date: Sat, 7 Feb 2026 10:24:26 +0100 Subject: docs: Add script maintenance requirements after hierarchy changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added new section "Script Maintenance After Hierarchy Changes" to CONTRIBUTING.md documenting the requirement to review and update scripts in scripts/ directory after any major source reorganization. Key points: - Lists when script review is required (file moves, renames, etc.) - Identifies scripts that commonly need updates (check_all.sh, gen_coverage_report.sh, build_win.sh, gen_assets.sh) - Provides verification steps to ensure scripts remain functional - Includes recent example (platform.cc → platform/platform.cc) - References automated verification via check_all.sh This prevents issues like the coverage script failing on moved files or verification scripts missing compilation failures in tools. Co-Authored-By: Claude Sonnet 4.5 --- doc/CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'doc/CONTRIBUTING.md') 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. + -- cgit v1.2.3