# Contributing to Espilon Thank you for your interest in contributing to Espilon! This document provides guidelines and instructions for contributing to the project. --- ## Table of Contents - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) - [Coding Standards](#coding-standards) - [Commit Guidelines](#commit-guidelines) - [Pull Request Process](#pull-request-process) - [Security Contributions](#security-contributions) - [Community](#community) --- ## Code of Conduct ### Our Standards - **Be respectful**: Treat everyone with respect and kindness - **Be collaborative**: Work together to improve the project - **Be responsible**: This is a security tool - use it ethically - **Be professional**: Maintain professional communication - **Be patient**: Help newcomers learn and grow ### Unacceptable Behavior - Harassment, discrimination, or offensive comments - Sharing malicious code or exploits for illegal purposes - Unauthorized testing against third-party systems - Trolling, insulting, or derogatory comments - Publishing others' private information **Violations**: Please report to project maintainers. Serious violations may result in being banned from the project. --- ## How Can I Contribute? ### Reporting Bugs **Before submitting a bug report**: 1. Check the [documentation](docs/) for common issues 2. Search [existing issues](https://github.com/yourusername/epsilon/issues) to avoid duplicates 3. Try to reproduce with the latest version **Good bug reports include**: - Clear, descriptive title - Steps to reproduce the issue - Expected vs actual behavior - ESP32 variant and board type - ESP-IDF version - Configuration (`sdkconfig` relevant parts) - Serial output/logs - Screenshots (if applicable) **Bug Report Template**: ```markdown ## Description [Clear description of the bug] ## Steps to Reproduce 1. Configure device with... 2. Execute command... 3. Observe error... ## Expected Behavior [What should happen] ## Actual Behavior [What actually happens] ## Environment - ESP32 Variant: ESP32/ESP32-S2/ESP32-S3/etc. - Board: DevKit/ESP32-CAM/Custom - ESP-IDF Version: v5.3.2 - Espilon Version: commit hash or version ## Logs ``` [Paste relevant logs here] ``` ## Additional Context [Any other relevant information] ``` ### Suggesting Features **Feature requests should**: - Have a clear use case - Align with project goals (security research/education) - Consider resource constraints (ESP32 limitations) - Include implementation ideas (if possible) **Feature Request Template**: ```markdown ## Feature Description [Clear description of the proposed feature] ## Use Case [Why is this feature needed? What problem does it solve?] ## Proposed Implementation [How could this be implemented? Consider:] - Memory requirements - CPU usage - Network bandwidth - Module structure - Configuration options ## Alternatives Considered [Other approaches you've thought about] ## Additional Context [Mockups, examples, references] ``` ### Contributing Code **Types of contributions welcome**: - Bug fixes - New modules or commands - Documentation improvements - Code quality improvements (refactoring, optimization) - Tests and test infrastructure - Security enhancements - Translations - Tool improvements (C2, flasher, etc.) **Getting started**: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test thoroughly 5. Submit a pull request --- ## Development Setup ### Prerequisites - ESP-IDF v5.3.2 or compatible - Python 3.8+ - Git - ESP32 development board (for testing) ### Fork and Clone ```bash # Fork repository on GitHub, then: git clone https://github.com/YOUR-USERNAME/epsilon.git cd epsilon # Add upstream remote git remote add upstream https://github.com/original-owner/epsilon.git ``` ### Set Up Development Environment ```bash # Install ESP-IDF cd ~/esp git clone --recursive --branch v5.3.2 https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh esp32 . ./export.sh # Install Python dependencies (for C2) cd /path/to/epsilon/tools/c2 pip3 install -r requirements.txt ``` ### Create Feature Branch ```bash # Update your fork git checkout main git pull upstream main # Create feature branch git checkout -b feature/your-feature-name ``` **Branch naming conventions**: - `feature/feature-name` - New features - `fix/bug-description` - Bug fixes - `docs/topic` - Documentation updates - `refactor/component-name` - Code refactoring - `test/test-description` - Test additions --- ## Coding Standards ### C Code (ESP32 Firmware) **Style Guide**: - **Indentation**: 4 spaces (NO tabs) - **Braces**: K&R style (opening brace on same line) - **Naming**: - Functions: `snake_case` (e.g., `process_command`) - Variables: `snake_case` (e.g., `device_id`) - Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_BUFFER_SIZE`) - Macros: `UPPER_SNAKE_CASE` - Structs: `snake_case_t` (e.g., `command_t`) **Example**: ```c #include "esp_log.h" #include "utils.h" #define TAG "MODULE" #define MAX_RETRIES 3 typedef struct { char name[32]; int value; } config_t; static int process_data(const uint8_t *data, size_t len) { if (data == NULL || len == 0) { ESP_LOGE(TAG, "Invalid parameters"); return -1; } for (size_t i = 0; i < len; i++) { // Process data } return 0; } ``` **Best Practices**: - Use ESP_LOG* macros for logging (not printf) - Check return values and handle errors - Free allocated memory (no leaks) - Use const for read-only parameters - Validate input parameters - Document complex logic with comments - Keep functions small and focused - No global mutable state (use static or pass context) - No magic numbers (use named constants) - No commented-out code (use git history) ### Python Code (C2 Server) **Style Guide**: [PEP 8](https://pep8.org/) - **Indentation**: 4 spaces - **Line length**: 100 characters max - **Naming**: - Functions: `snake_case` - Classes: `PascalCase` - Constants: `UPPER_SNAKE_CASE` - Private: `_leading_underscore` **Example**: ```python import logging from typing import List, Optional logger = logging.getLogger(__name__) class DeviceManager: """Manages connected ESP32 devices.""" def __init__(self): self._devices = {} def add_device(self, device_id: str, connection) -> None: """Add a new device to the registry.""" if not device_id: raise ValueError("device_id cannot be empty") self._devices[device_id] = connection logger.info(f"Device added: {device_id}") def get_device(self, device_id: str) -> Optional[object]: """Retrieve device by ID.""" return self._devices.get(device_id) ``` **Best Practices**: - Type hints for function signatures - Docstrings for classes and public functions - Use logging module (not print statements) - Handle exceptions appropriately - Use context managers (`with` statements) - Run `black` for formatting - Run `flake8` for linting **Tools**: ```bash # Format code black tools/c2/ # Check style flake8 tools/c2/ # Type checking mypy tools/c2/ ``` ### Documentation **Markdown Style**: - Use ATX-style headers (`#`, `##`, `###`) - Code blocks with language specifiers - Tables for structured data - Lists for sequential or unordered items **Code Comments**: - Explain **why**, not **what** (code shows what) - Keep comments up-to-date with code - Use TODO/FIXME/NOTE for temporary notes - Remove obsolete comments --- ## Commit Guidelines ### Commit Message Format ``` ():