Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
251 lines (195 loc) · 6.28 KB

CONTRIBUTING.md

File metadata and controls

251 lines (195 loc) · 6.28 KB
Raw

Contributing to ESP32-WiFi-Manager

First off, thank you for considering contributing to ESP32-WiFi-Manager! It's people like you that make this project better for everyone.

Code of Conduct

By participating in this project, you are expected to uphold our code of conduct:

  • Be respectful and inclusive
  • Welcome newcomers and help them get started
  • Focus on what is best for the community
  • Show empathy towards other community members

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Bug Report Template:

  • Description: Clear description of the bug
  • Steps to Reproduce: Step-by-step instructions
  • Expected Behavior: What you expected to happen
  • Actual Behavior: What actually happened
  • Environment:
    • ESP32-S3 board version (v1.0 or v1.1)
    • PlatformIO or Arduino IDE version
    • Operating system
    • Library versions
  • Serial Output: Include relevant serial monitor output
  • Screenshots: If applicable

Suggesting Enhancements

Enhancement suggestions are welcome! Please provide:

  • Clear use case: Why is this enhancement useful?
  • Detailed description: What should it do?
  • Possible implementation: If you have ideas
  • Alternatives considered: Other approaches you've thought about

Pull Requests

  1. Fork the Repository

    git clone https://github.com/EmilyKeer/ESP32-WiFi-Manager.git
cd ESP32-WiFi-Manager

  2. Create a Branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  3. Make Your Changes

    • Follow the code style guidelines below
    • Add comments where necessary
    • Update documentation if needed

  4. Test Your Changes

    • Build and upload to ESP32-S3 hardware
    • Test all affected features
    • Verify serial commands work
    • Check web interface functionality
    • Test on both WiFi connection and disconnection

  5. Commit Your Changes

    git add .
git commit -m "Brief description of changes"

    Commit message format:

    • feat: Add new LED pattern feature
    • fix: Resolve WiFi reconnection issue
    • docs: Update installation instructions
    • refactor: Improve LED controller code
    • test: Add unit tests for WiFiManager

  6. Push to Your Fork

    git push origin feature/your-feature-name

  7. Submit a Pull Request

    • Go to the original repository
    • Click "New Pull Request"
    • Select your branch
    • Fill in the PR template with details
    • Link any related issues

Development Setup

Requirements

  • PlatformIO or Arduino IDE
  • ESP32-S3-DevKitC-1 development board
  • USB-C cable

Setup Steps

  1. Install PlatformIO (recommended)

    • Install VS Code
    • Install PlatformIO extension

  2. Clone and Build

    git clone https://github.com/EmilyKeer/ESP32-WiFi-Manager.git
cd ESP32-WiFi-Manager
pio run

  3. Upload and Monitor

    pio run --target upload
pio device monitor

Code Style Guidelines

C/C++ Code Style

  1. Indentation: 4 spaces (no tabs)

  2. Naming Conventions:

    • Classes: PascalCase (e.g., WiFiManager)
    • Functions: camelCase (e.g., setColor())
    • Variables: camelCase (e.g., currentRed)
    • Constants: UPPER_CASE (e.g., RGB_LED_PIN)
    • Private members: camelCase (e.g., serverRunning)

  3. File Structure:

    • Header guards: #ifndef FILE_NAME_H
    • Include order: Arduino libraries → Third-party → Project headers
    • Copyright header at top of each file

  4. Comments:

    // Single-line comments for brief explanations

/**
 * Multi-line comments for function documentation
 * @param paramName Description of parameter
 * @return Description of return value
 */

  5. Braces:

    // Use K&R style
void function() {
    if (condition) {
        // code
    } else {
        // code
    }
}

HTML/CSS/JavaScript Style

  1. Indentation: 4 spaces
  2. Naming: kebab-case for CSS classes
  3. Comments: Use <!-- --> for HTML, /* */ for CSS
  4. Keep embedded web code minimal and well-formatted

Testing Guidelines

Before Submitting a PR

  • Code compiles without errors
  • Code compiles without warnings
  • Tested on actual ESP32-S3 hardware
  • WiFi connection works
  • Web interface loads correctly
  • LED control functions properly
  • Serial commands work as expected
  • No memory leaks or crashes during extended use
  • Documentation updated (if applicable)

Testing Checklist

  1. WiFi Functionality:

    • Scan networks
    • Connect to WPA2 network
    • Connect to open network
    • Automatic reconnection
    • Disconnect and forget

  2. LED Control:

    • Set RGB colors
    • Adjust brightness
    • Preset colors work
    • Rainbow effect
    • Turn off

  3. Web Interface:

    • Status page loads
    • LED control page loads
    • Tab switching works
    • Responsive on mobile
    • API endpoints respond correctly

  4. Serial Interface:

    • All commands execute
    • Output is readable
    • Error messages are clear

Project Structure

ESP32-WiFi-Manager/
├── include/          # Header files
├── src/              # Source files
├── .github/          # GitHub templates
├── platformio.ini    # PlatformIO config
├── README.md         # Main documentation
├── LICENSE           # MIT License
├── CONTRIBUTING.md   # This file
└── NOTICE            # Third-party attributions

Documentation

  • Update README.md if you add/change features
  • Add inline comments for complex logic
  • Update API documentation if endpoints change
  • Include examples in pull request description

Questions?

Feel free to:

  • Open an issue for questions
  • Check existing issues and pull requests
  • Reach out in the pull request comments

Recognition

Contributors will be recognized in:

  • GitHub contributors page
  • Future CONTRIBUTORS.md file (if created)
  • Release notes for significant contributions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to ESP32-WiFi-Manager!