diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 813727b5..ebe412a3 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,6 @@ # WLED - ESP32/ESP8266 LED Controller Firmware -WLED is a fast and feature-rich implementation of an ESP32 and ESP8266 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI-based chipsets. The project consists of C++ firmware for microcontrollers and a modern web interface. +WLED is a fast and feature-rich implementation of an ESP32 and ESP8266 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI-based chipsets. The project consists of C++ firmware for microcontrollers and a modern web interface. WLED-MM is a fork of WLED that concentrates on higher performance (esp32, esp32-s3, boards with PSRAM), large installs and advanced audio analysis. Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. @@ -27,9 +27,26 @@ The build has two main phases: 2. **Hardware Compilation** (`pio run`): - Compiles C++ firmware for various ESP32/ESP8266 targets - - Common environments: `nodemcuv2`, `esp32dev`, `esp8266_2m` + - Common environments: `esp32_4MB_V4_M`, `esp32_16MB_V4_S_HUB75`, `esp32S3_8MB_PSRAM_M_qspi`, `esp32_16MB_V4_M_eth`, `esp8266_4MB_S`, `esp32dev_compat` - List all targets: `pio run --list-targets` +## Before Finishing Work + +**CRITICAL: You MUST complete ALL of these steps before marking your work as complete:** + +1. **Build at least one hardware environment**: `pio run -e esp32_4MB_V4_M` -- Set timeout to 30+ minutes. NEVER CANCEL. + - Choose `esp32_4MB_V4_M` as it's a common, representative environment + - See "Hardware Compilation" section above for the full list of common environments + - The build MUST complete successfully without errors + - If the build fails, fix the issue before proceeding + - **DO NOT skip this step** - it validates that firmware compiles with your changes + +2. **For web UI changes only**: Manually test the interface + - See "Manual Testing Scenarios" section below + - Verify the UI loads and functions correctly + +**If any of these validation steps fail, you MUST fix the issues before finishing. Do NOT mark work as complete with failing builds or tests.** + ## Validation and Testing ### Web UI Testing @@ -42,9 +59,10 @@ The build has two main phases: ### Code Validation - **No automated linting configured** - follow existing code style in files you edit - **Code style**: Use tabs for web files (.html/.css/.js), spaces (2 per level) for C++ files +- **Language**: The repository language is English (british, american, canadian, or australian). If you find other languages, suggest a translation into English. - **C++ formatting available**: `clang-format` is installed but not in CI - **Always run tests before finishing**: `npm test` -- **Always run a build for the common environment before finishing** +- **MANDATORY: Always run a hardware build before finishing** (see "Before Finishing Work" section below) ### Manual Testing Scenarios After making changes to web UI, always test: @@ -64,7 +82,7 @@ wled00/ # Main firmware source (C++) │ ├── settings*.htm # Settings pages │ └── *.js/*.css # Frontend resources ├── *.cpp/*.h # Firmware source files - └── html_*.h # Generated embedded web files (DO NOT EDIT) + └── html_*.h # Auto-generated embedded web files (DO NOT EDIT, DO NOT COMMIT) tools/ # Build tools (Node.js) ├── cdata.js # Web UI build script └── cdata-test.js # Test suite @@ -80,7 +98,7 @@ package.json # Node.js dependencies and scripts - `wled00/wled.h` - Main firmware configuration - `platformio.ini` - Hardware build targets and settings -### Development Workflow +### Development Workflow (applies to agent mode only) 1. **For web UI changes**: - Edit files in `wled00/data/` - Run `npm run build` to regenerate headers @@ -100,10 +118,16 @@ package.json # Node.js dependencies and scripts ## Build Timing and Timeouts -- **Web UI build**: 3 seconds - Set timeout to 30 seconds minimum -- **Test suite**: 40 seconds - Set timeout to 2 minutes minimum -- **Hardware builds**: 15+ minutes - Set timeout to 30+ minutes minimum -- **NEVER CANCEL long-running builds** - PlatformIO downloads and compilation can take significant time +**IMPORTANT: Use these timeout values when running builds:** + +- **Web UI build** (`npm run build`): 3 seconds typical - Set timeout to 30 seconds minimum +- **Test suite** (`npm test`): 40 seconds typical - Set timeout to 120 seconds (2 minutes) minimum +- **Hardware builds** (`pio run -e [target]`): 15-20 minutes typical for first build - Set timeout to 1800 seconds (30 minutes) minimum + - Subsequent builds are faster due to caching + - First builds download toolchains and dependencies which takes significant time +- **NEVER CANCEL long-running builds** - PlatformIO downloads and compilation require patience + +**When validating your changes before finishing, you MUST wait for the hardware build to complete successfully. Set the timeout appropriately and be patient.** ## Troubleshooting @@ -121,19 +145,29 @@ package.json # Node.js dependencies and scripts ## Important Notes -- **DO NOT edit `wled00/html_*.h` files** - they are auto-generated -- **Always commit both source files AND generated html_*.h files** -- **Web UI must be built before firmware compilation** +- **Always commit source files** +- **Web UI re-built is part of the platformio firmware compilation** +- **do not commit generated html_*.h files** +- **DO NOT edit `wled00/html_*.h` files** - they are auto-generated. If needed, modify Web UI files in `wled00/data/`. - **Test web interface manually after any web UI changes** +- When reviewing a PR: the PR author does not need to update/commit generated html_*.h files - these files will be auto-generated when building the firmware binary. +- **If you are not sure about something, just answer that you are not sure.** Gather more information instead of continuing with a wild guess. +- If asked for an analysis, assessment or web research, **always provide references** to justify your conclusions. - **Use VS Code with PlatformIO extension for best development experience** - **Hardware builds require appropriate ESP32/ESP8266 development board** ## CI/CD Pipeline -The GitHub Actions workflow: + +**The GitHub Actions CI workflow will:** 1. Installs Node.js and Python dependencies 2. Runs `npm test` to validate build system -3. Builds web UI with `npm run build` -4. Compiles firmware for multiple hardware targets +3. Builds web UI with `npm run build` (automatically run by PlatformIO) +4. Compiles firmware for ALL hardware targets listed in `default_envs` (MUST succeed for all) 5. Uploads build artifacts -Match this workflow in your local development to ensure CI success. +**To ensure CI success, you MUST locally:** +- Run `npm test` and ensure it passes +- Run `pio run -e esp32_4MB_V4_M` (or another common environment from "Hardware Compilation" section) and ensure it completes successfully +- If either fails locally, it WILL fail in CI + +**Match this workflow in your local development to ensure CI success. Do not mark work complete until you have validated builds locally.**