Code Review & Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Code Review & Contribution Guidelines define the standards and procedures for modifying the Muse Gadget firmware and its associated board ports. These guidelines ensure that contributions maintain system stability, adhere to security protocols, and follow established architectural patterns for the ESP32 Device SDK.
This documentation covers the technical requirements for automated reviews, security vulnerability reporting, and the manual verification steps required before code is merged into the repository. It specifically addresses the integration of the Muse Gadget SDK with various hardware targets such as the ESP32-C5 and S3.
Sources: board-port/esp32/README.md, board-port/esp32/AGENTS.md:18-28
Automated Code Review Rules
The project uses automated configuration to enforce specific coding standards during the review process. These rules are defined to prevent common errors in production code and maintain a consistent style across different repository types.
Custom Linting Rules
The system flags specific code patterns that are prohibited in production environments.
| Rule Name | Description | Scope |
|---|---|---|
| No console logs | Flags console.log calls left in production code. | Excludes legacy-monolith and *-sandbox |
| React style guide | Enforces the React style guide defined in docs/react-style-guide.md. | Restricted to web-* and design-system |
Sources: cubic-config/cubic.yaml:1-15
Contribution Verification Checklist
Before submitting or handing back work, contributors must complete a multi-step verification process to ensure the firmware remains functional across supported boards.
Pre-submission Requirements
- Build Validation: Run
idf.py buildfor the specific board touched. The build must pass the size check under the partition slot limit. - Host Testing: All host-side Python unit tests must pass.
- Boot Verification: If the firmware was flashed, the boot log must reach the "starting" state without entering a panic or reboot loop.
Sources: board-port/esp32/AGENTS.md:387-394
Testing Architecture
The project utilizes host-side Python unittest harnesses that compile C/C++ code against fakes. This allows testing logic without physical hardware.
The diagram shows the flow for executing host-side tests which require a preliminary build to ensure managed_components/ are present.
Sources: board-port/esp32/AGENTS.md:371-385, board-port/esp32/README.md:213-224
Security and Vulnerability Guidelines
Maintaining the security of the Muse Gadget SDK is a priority. Contributors must follow specific protocols for reporting vulnerabilities and managing supported versions.
Version Support
Security updates are provided only for specific versions of the project.
| Version | Supported |
|---|---|
| 5.1.x | ✅ |
| 5.0.x | ❌ |
| 4.0.x | ✅ |
| < 4.0 | ❌ |
Sources: SECURITY.md:5-12
Reporting Procedures
Vulnerabilities must be reported through official channels rather than public issues. Contributors should expect periodic updates on the status of reported vulnerabilities until they are accepted or declined.
Sources: SECURITY.md:14-22
Architectural Standards for New Features
When adding features or commands, contributors must follow the "Noise" control pattern to ensure proper synchronization and communication with the Muse backend.
Command Registration Flow
New commands must be advertised and handled through the noise_control.cpp and app.c modules.
This sequence illustrates the non-blocking execution pattern required for slow operations like sensor reading or network discovery.
Sources: board-port/esp32/AGENTS.md:310-335, board-port/esp32/main/noise_control.cpp:1150-1200
Naming Conventions
The project strictly enforces the use of the "Muse" brand over internal code names.
- User-facing text: Must use "Muse" or "Muse Gadget".
- Code Identifiers: Use
museormuse_gadget. Avoidhatchin new file names or identifiers. - Exceptions: Legacy identifiers like
hatch.metaaivm.comor specific setup commands (hatch.token) remain for server compatibility.
Sources: board-port/esp32/AGENTS.md:347-369
Firmware Release Workflow
Contributions that trigger releases follow a structured GitHub Actions workflow. This ensures that only verified code is packaged for distribution.
- Checkout: Clones the SDK at a pinned commit.
- Overlay: Applies the
board-port/tree from the repository. - Injection: Injects the
GADGET_SDK_TOKENfrom repository secrets (it must never be committed to the code). - Build: Uses a Dockerized ESP-IDF v6.0.1 environment.
- Package: Zips binaries (
bootloader.bin,partition-table.bin,muse-gadget.bin) with flash scripts.
Sources: workflows/build-release.yml:1-50
The Code Review & Contribution Guidelines provide a technical framework to ensure all changes to the Muse Gadget SDK are secure, well-tested, and architecturally consistent. Following these procedures is mandatory for maintaining the integrity of the open-source firmware across the diverse range of supported ESP32 boards.