Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
229 lines (162 loc) · 5.28 KB

CONTRIBUTING.md

File metadata and controls

229 lines (162 loc) · 5.28 KB

Contributing to HomeKey-ESP32

Thank you for your interest in contributing to HomeKey-ESP32! We welcome contributions from the community and are pleased to have you join us.

Note

AI/LLM Guidelines

Use of LLMs is permitted to produce the code or content for the wiki as long as the following guidelines are followed:

  • Ensure no unnecessary information is added
  • Ensure no unnecessary dependencies are added
  • Ensure the PR does not include changes to unrelated files and/or unrelated changes within the same file, keep it focused on the purpose of the PR

How to Contribute

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone --recursive https://github.com/your-username/HomeKey-ESP32.git
cd HomeKey-ESP32

Development Setup

  1. Install ESP-IDF (see the ESP-IDF Installation Guide for details):

  2. Install web development dependencies:

    cd data
## You need Bun instead, feel free to use npm or yarn instead if you prefer
bun install

  3. Update submodules:

    git submodule update --init --recursive

Making Changes

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes following our coding standards (see below)

  3. Test your changes:

    • For ESP32 firmware: idf.py build && idf.py flash monitor
    • For web interface: cd data && npm run dev

  4. Commit your changes:

    git add .
git commit -m "feat: add your feature description"

  5. Push to your fork:

    git push origin feature/your-feature-name

  6. Create a Pull Request on GitHub

Pull Request Process

  1. Title your PR with a clear and descriptive title
  2. Provide a detailed description of your changes and the problem you're trying to solve
  3. Request review from maintainers
  4. Address review feedback promptly
  5. Squash commits if requested

Types of Contributions

Bug Reports

  • Include steps to reproduce
  • Provide system information
  • Include relevant logs and/or screenshots

Feature Requests

  • Explain the use case
  • Describe the expected behavior
  • Consider implementation complexity

Code Contributions

  • Firmware: ESP32 C++ code in main/
  • Web Interface: Svelte code in data/
  • Documentation: Markdown files in docs/content

Documentation

  • Fix typos and improve clarity
  • Add missing documentation
  • Update outdated information

Testing

  • Test on different hardware configurations
  • Report compatibility issues
  • Validate new features
  • Performance benchmarking

Coding Standards

C++ Code (ESP32 Firmware)

// Use consistent indentation (2 spaces)
// Use meaningful variable names
// Add comments for complex logic

class ExampleClass {
public:
  void exampleMethod();
  
private:
  int m_exampleVariable;
};

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test changes
  • chore: Maintenance tasks

Examples:

feat(nfc): add support for multiple card types
fix(web): resolve configuration save issue
docs: update installation guide for Windows

Testing Guidelines

Hardware Compatibility

Test on different ESP32 variants:

  • ESP32-WROOM-32
  • ESP32-S3
  • ESP32-C3
  • ESP32-C6

Security Guidelines

Code Security

  • Validate all inputs
  • Use secure random number generation
  • Implement proper error handling
  • Avoid hardcoded secrets

Cryptographic Operations

  • Use established libraries
  • Follow cryptographic best practices
  • Secure key storage (not implemented atm)
  • Proper random seeding

Network Security

  • Validate certificates
  • Implement proper authentication
  • Avoid information leakage

Getting Help

Before Asking

  1. Check existing issues and discussions
  2. Read the documentation thoroughly
  3. Search closed issues for similar problems
  4. Test with the latest development version

How to Ask

  1. Use the appropriate template
  2. Provide complete information
  3. Include relevant logs and screenshots
  4. Be specific about your environment
  5. Describe what you've already tried

Community Resources

  • Discord: Join our server
  • GitHub Discussions: For general questions and ideas
  • GitHub Issues: For bug reports and feature requests
  • Documentation: Read the docs

Recognition

Contributors will be:

  • Given credit in release notes
  • Invited to the contributors team after significant contributions

📜 Legal

License

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

Copyright

You retain copyright to your contributions. We ask that you license them under the MIT license so they can be included in the main project.

Thank you for contributing to HomeKey-ESP32! Your efforts help make smart home technology more accessible to everyone.