Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (133 loc) · 4.06 KB

CONTRIBUTING.md

File metadata and controls

181 lines (133 loc) · 4.06 KB

Contributing to LAN-IOT

Thank you for your interest in contributing to LAN-IOT! This document provides guidelines for contributing to the project.

Code of Conduct

By participating in this project, you agree to maintain a respectful and collaborative environment.

How to Contribute

Reporting Issues

  • Check if the issue already exists in the issue tracker
  • Provide a clear description of the problem
  • Include steps to reproduce the issue
  • Specify your environment (ESP-IDF version, hardware, OS)
  • Include relevant log output

Submitting Changes

  1. Fork the repository
  2. Create a feature branch: 
    git checkout -b feature/your-feature-name
  3. Make your changes:
    • Follow the existing code style
    • Add comments for complex logic
    • Test your changes thoroughly
  4. Commit your changes: 
    git commit -m "Add: brief description of changes"
    Use conventional commit messages:
    • Add: for new features
    • Fix: for bug fixes
    • Update: for improvements
    • Docs: for documentation changes
  5. Push to your fork: 
    git push origin feature/your-feature-name
  6. Create a Pull Request

Pull Request Guidelines

  • Provide a clear description of the changes
  • Reference any related issues
  • Ensure all tests pass
  • Update documentation if needed
  • Keep changes focused and atomic

Development Setup

Prerequisites

  • ESP-IDF v5.5.1
  • ESP32-S3 development board
  • Git

Setting Up Development Environment

  1. Clone the repository:

    git clone https://github.com/your-username/lan-iot.git
cd lan-iot

  2. Set up ESP-IDF:

    . $HOME/esp/esp-idf/export.sh

  3. Create your configuration:

    cp main/app_config.h.bak main/app_config.h
# Edit main/app_config.h with your settings

  4. Build the project:

    idf.py build

Code Style

C Code

  • Use 4 spaces for indentation (no tabs)
  • Follow ESP-IDF coding style
  • Use descriptive variable and function names
  • Add comments for complex logic
  • Keep functions focused and small

Naming Conventions

  • snake_case for functions and variables
  • UPPER_CASE for constants and macros
  • Prefix static functions with s_ or make them static

Comments

  • Use // for single-line comments
  • Use /* */ for multi-line comments
  • Document public APIs with descriptive comments

Testing

Before submitting a pull request:

  1. Build the project without warnings:

    idf.py build

  2. Test on actual hardware if possible

  3. Verify basic functionality:

    • WiFi connection
    • Certificate acquisition
    • HTTPS server operation
    • WSS/TCP services

Documentation

  • Update README.md if adding new features
  • Add inline code documentation
  • Update configuration examples if needed

Security

Reporting Security Issues

DO NOT open public issues for security vulnerabilities.

Instead, please email security concerns privately to the maintainers.

Handling Credentials

  • Never commit secrets, tokens, or credentials
  • Use app_config.h.bak as a template only
  • Ensure main/app_config.h is in .gitignore

Areas for Contribution

We welcome contributions in the following areas:

Features

  • Additional service protocols (MQTT, CoAP, etc.)
  • Enhanced monitoring and metrics
  • Power management improvements
  • OTA update support

Documentation

  • Usage examples
  • Deployment guides
  • Troubleshooting tips
  • Architecture diagrams

Testing

  • Unit tests
  • Integration tests
  • Hardware compatibility testing

Bug Fixes

  • Check the issue tracker for open bugs
  • Verify and fix reported issues

License

By contributing to LAN-IOT, you agree that your contributions will be licensed under the Apache License 2.0.

Questions?

If you have questions about contributing, feel free to:

  • Open a discussion in the repository
  • Ask in the issues section (for general questions)
  • Check existing documentation

Recognition

Contributors will be recognized in the project documentation and release notes.

Thank you for contributing to LAN-IOT! 🎉