Contribution & Security Policies
Relevant source files
The following files were used as context for generating this wiki page:
The Contribution and Security Policies define the standards, procedures, and safety protocols for participating in the Muse Gadget SDK project. These policies ensure that contributions remain high-quality, secure, and inclusive while protecting the project’s integrity and its users.
Contribution Guidelines
The project facilitates contributions through a structured Pull Request (PR) process and a mandatory licensing agreement. Contributors must follow specific technical and legal steps to ensure their code integrates safely into the main branch.
Pull Request Process
To contribute code or documentation, you must follow these steps:
- Fork the repository and create a feature branch from
main. - Add tests for any new code functionality.
- Update the documentation if you change any APIs.
- Verify that the entire test suite passes successfully.
- Ensure the code meets linting standards.
- Complete the Contributor License Agreement (CLA).
Sources: CONTRIBUTING.md:4-13
Contributor License Agreement (CLA)
The project requires a signed CLA before any pull request can be accepted. This is a one-time requirement for individuals working on Meta’s open-source projects. You can complete the agreement at code.facebook.com/cla.
Sources: CONTRIBUTING.md:15-19
Technical Standards for Contributions
When contributing to specific modules like the ESP32 firmware, you must adhere to additional technical requirements:
- Version Pinning: Firmware must be built with ESP-IDF version 6.0.1.
- Documentation: Technical facts for new devices must be cited from vendor sources, schematics, or reference firmware.
- Verification: New board support requires a scratch build and verification that every overlay line reached the generated
sdkconfig.
Sources: esp32/README.md:80-82, esp32/devices/AGENTS.md:109-113, esp32/devices/AGENTS.md:310-316
Security Policy
The security policy outlines how the project handles vulnerabilities and which versions receive active maintenance.
Supported Versions
Security updates are provided for specific major and minor versions of the SDK.
| Version | Supported |
|---|---|
| 5.1.x | ✅ |
| 5.0.x | ❌ |
| 4.0.x | ✅ |
| < 4.0 | ❌ |
Sources: SECURITY.md:5-12
Vulnerability Reporting
The project uses a dedicated channel for security bugs to prevent public disclosure of exploits.
- Bounty Program: Report security vulnerabilities through the Facebook Whitehat program.
- Prohibition: Do not file public GitHub issues for security-related bugs.
Sources: CONTRIBUTING.md:25-28, SECURITY.md:14-21
Data and Hardware Security
For hardware implementations, the project provides specific security recommendations:
- NVS Encryption: Enabling Non-Volatile Storage (NVS) encryption is strongly recommended to protect Wi-Fi credentials and device tokens stored in flash.
- SDK Tokens: Treat SDK tokens as identifiers rather than passwords; if a token leaks, you must revoke it on the Muse portal and generate a new one.
Sources: esp32/README.md:183-192
Code of Conduct
The Code of Conduct establishes the community standards to ensure a harassment-free experience for all participants.
Standards of Behavior
The project defines expected positive behaviors and prohibited actions to maintain a professional environment.
| Category | Examples |
|---|---|
| Positive Behavior | Using inclusive language, respecting differing viewpoints, and accepting constructive criticism. |
| Unacceptable Behavior | Sexualized language/imagery, trolling, personal or political attacks, and doxxing. |
Sources: CODE_OF_CONDUCT.md:12-32
Enforcement Flow
Maintainers are responsible for enforcing these standards. The following diagram illustrates the reporting and investigation process.
The diagram shows the lifecycle of a conduct report, from initial contact to potential enforcement actions taken by project leadership.
Sources: CODE_OF_CONDUCT.md:34-62
Issue Tracking
GitHub issues are used to track public bugs. When reporting an issue, you must provide:
- A clear description of the bug.
- Sufficient instructions to reproduce the issue.
Sources: CONTRIBUTING.md:21-23
Summary
The contribution and security policies provide a framework for maintaining the Muse Gadget SDK as a safe and reliable open-source resource. By requiring CLAs, standardized PR processes, and private security reporting, the project balances community accessibility with professional-grade security and conduct standards.