Contributing to IPECMD Wrapper¶

Thank you for your interest in contributing to the IPECMD Wrapper project! This document provides guidelines and information for contributors.

🚀 Quick Start¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/s-celles/ipecmd-wrapper.git
cd ipecmd-wrapper

Set up the development environment:
```
python setup_dev.py
```
Activate the virtual environment:
Windows: .venv\Scripts\activate
Unix/macOS: source .venv/bin/activate
Run tests to ensure everything works:
```
python -m pytest tests/ -v
```

🛠️ Development Workflow¶

Setting Up Your Development Environment¶

We provide several ways to set up your development environment:

Automated setup (recommended):
```
python setup_dev.py
```

Manual setup:

python -m venv .venv
source .venv/bin/activate  # Unix/macOS
# or
.venv\Scripts\activate     # Windows

pip install -e .[dev]
pre-commit install

Using Makefile (Unix/macOS):
```
make setup-dev
```

Running Tests¶

We use pytest for testing with several test categories:

# Run all tests
python -m pytest

# Run tests with coverage
python -m pytest --cov=ipecmd_wrapper

# Run only unit tests
python -m pytest -m unit

# Run only integration tests
python -m pytest -m integration

# Run specific test file
python -m pytest tests/test_core.py

# Run tests in parallel
python -m pytest -n auto

Code Quality¶

We maintain high code quality standards:

# Format and lint code (replaces black, isort, flake8)
ruff check --fix .
ruff format .

# Type checking
mypy .

# Security analysis
bandit -r ipecmd_wrapper/

# Run all pre-commit hooks
pre-commit run --all-files

📋 Testing Guidelines¶

Test Categories¶

We organize tests into several categories using pytest markers:

@pytest.mark.unit: Unit tests for individual functions/classes
@pytest.mark.integration: Integration tests for component interaction
@pytest.mark.performance: Performance and benchmarking tests
@pytest.mark.compatibility: Cross-platform compatibility tests
@pytest.mark.slow: Tests that take longer to run

Writing Tests¶

Test file naming: Use test_*.py format
Test function naming: Use test_* format
Test class naming: Use Test* format
Use descriptive test names: test_upload_with_valid_hex_file_succeeds
Include docstrings: Explain what the test verifies
Use fixtures: For common setup/teardown
Mock external dependencies: Use unittest.mock or pytest-mock

Test Structure¶

def test_feature_with_valid_input_succeeds():
    """Test that feature works correctly with valid input."""
    # Arrange
    input_data = "valid_input"
    expected_result = "expected_output"

    # Act
    result = feature_function(input_data)

    # Assert
    assert result == expected_result

🔧 Code Style¶

We follow PEP 8 with some modifications:

Line length: 88 characters (Ruff default)
Use double quotes for strings
Use type hints where appropriate
Document public functions and classes

Pre-commit Hooks¶

We use pre-commit to ensure code quality:

# Install pre-commit hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files

📝 Documentation¶

Code Documentation¶

Use docstrings for all public functions, classes, and modules
Follow Google docstring format
Include type hints in function signatures
Document parameters, return values, and exceptions

Example:¶

def upload_firmware(hex_file: str, device: str, programmer: str = "pickit3") -> bool:
    """Upload firmware to PIC microcontroller.

    Args:
        hex_file: Path to the hex file to upload
        device: Target device name (e.g., "PIC16F876A")
        programmer: Programmer type (default: "pickit3")

    Returns:
        True if upload successful, False otherwise

    Raises:
        FileNotFoundError: If hex file doesn't exist
        RuntimeError: If upload fails
    """

🚀 Submitting Changes¶

Pull Request Process¶

Create a feature branch: git checkout -b feature/your-feature-name
Make your changes: Follow the code style and testing guidelines
Write tests: Add tests for new functionality
Run tests: Ensure all tests pass
Update documentation: Update README, docstrings, etc.
Commit changes: Use clear, descriptive commit messages
Push to your fork: git push origin feature/your-feature-name
Create pull request: Submit a PR against the main branch

Commit Messages¶

Use conventional commit format:

type(scope): description

feat(core): add support for PIC18F series
fix(cli): handle missing hex file gracefully
docs(readme): update installation instructions
test(core): add unit tests for device detection

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - test: Adding or updating tests - refactor: Code refactoring - style: Code style changes - ci: CI/CD changes

Code Review¶

All changes must be reviewed before merging:

Automated checks: CI must pass
Manual review: At least one maintainer approval
Testing: New features must include tests
Documentation: User-facing changes need documentation updates

🐛 Bug Reports¶

When reporting bugs, please include:

Description: Clear description of the issue
Steps to reproduce: Minimal steps to reproduce the bug
Expected behavior: What should happen
Actual behavior: What actually happens
Environment: OS, Python version, package versions
Code samples: Minimal code that reproduces the issue

💡 Feature Requests¶

When requesting features:

Use case: Describe why this feature would be useful
Proposed solution: How you think it should work
Alternatives: Other solutions you've considered
Impact: Who would benefit from this feature

📜 License¶

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

🤝 Code of Conduct¶

This project follows the Contributor Covenant Code of Conduct. Please be respectful and inclusive in all interactions.

🆘 Getting Help¶

If you need help:

Check the documentation
Search existing issues
Create a new issue with the "question" label
Join our discussions in the GitHub repository

🙏 Recognition¶

Contributors are recognized in:

Git commit history
Release notes
Contributors section in README
GitHub contributors graph

Thank you for contributing to IPECMD Wrapper! 🎉