Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (108 loc) · 4.34 KB

CONTRIBUTING.md

File metadata and controls

145 lines (108 loc) · 4.34 KB

Contributing to MeshC2

Thank you for your interest in contributing to MeshC2! This document provides guidelines for contributing to this project.

Code of Conduct

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

How to Contribute

Reporting Issues

  • Use the GitHub issue tracker to report bugs or suggest features
  • Before creating an issue, please search existing issues to avoid duplicates
  • Include detailed information about your environment and steps to reproduce the issue
  • For security vulnerabilities, please see our Security Policy

Contributing Code

  1. Fork the repository and create your branch from main

  2. Install development dependencies:

    git clone https://github.com/your-username/meshc2.git
cd meshc2
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

  3. Run tests to ensure everything works:

    python -m pytest tests/

  4. Make your changes:

    • Follow the existing code style and conventions
    • Add tests for new functionality
    • Update documentation as needed
    • Ensure security best practices are followed

  5. Test your changes:

    # Run unit tests
python -m pytest tests/

# Test installation (in a VM or container)
./install.sh                    # Interactive mode for testing
# OR for automated testing:
./install.sh --upgrade-only     # Skip prompts in CI/CD
./validate_install.sh

  6. Commit your changes:

    • Use clear, descriptive commit messages
    • Follow conventional commit format when possible
    • Sign your commits if possible

  7. Submit a pull request:

    • Provide a clear description of the changes
    • Reference any related issues
    • Include testing information

Development Guidelines

Code Style

  • Follow PEP 8 Python style guidelines
  • Use meaningful variable and function names
  • Include docstrings for all public functions and classes
  • Comment complex logic and security-relevant code

Security Considerations

This project handles remote command execution and device access. Please:

  • Never commit secrets or credentials
  • Validate all inputs thoroughly
  • Use secure defaults in configuration
  • Test security controls before submitting
  • Follow principle of least privilege

Testing

  • Write tests for new functionality
  • Include both unit tests and integration tests
  • Test with real hardware when possible
  • Test installation and uninstallation procedures

Documentation

  • Update README.md for user-facing changes
  • Update inline documentation and comments
  • Include usage examples for new features
  • Update installation instructions if needed

Development Environment

Hardware Requirements

For full testing, you'll need:

  • A Meshtastic-compatible device (Heltec, RAK, ESP32-based)
  • USB cable for device connection
  • Linux development environment (Ubuntu 20.04+ recommended)

Mock Development

For development without hardware:

  • Use use_real_device: false in config.yml
  • Mock interface simulates device interactions
  • Integration tests work without hardware

Project Structure

meshc2/
├── src/meshtastic_troubleshoot/  # Main application code
│   ├── components/               # Core service components
│   └── utils/                    # Utility modules
├── config/                       # Configuration templates
├── scripts/                      # Service files and scripts
├── tests/                        # Test suite
├── install.sh                    # Installation script
├── uninstall.sh                  # Removal script
└── validate_install.sh           # Installation validation

Release Process

  1. Update version numbers in relevant files
  2. Update CHANGELOG.md with new features and fixes
  3. Create a release branch
  4. Run full test suite including hardware tests
  5. Update documentation
  6. Create release notes
  7. Tag the release

Questions?

  • Open an issue for questions about contributing
  • Check existing documentation in the repository
  • Review the project's README.md for basic information

License

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