ble-reticulum/CONTRIBUTING.md

Contributing to Reticulum BLE Interface

Thank you for your interest in contributing! This document provides guidelines and information for contributors.

Note: This guide is for developing/contributing to the BLE interface code itself. If you want to use the BLE interface in your Reticulum setup, see the Installation section in README.md.

Getting Started

Prerequisites

• Python 3.8 or higher
• Git
• Linux system with BlueZ 5.x
• BLE-enabled hardware for integration testing (Raspberry Pi Zero W recommended, but not required for unit tests)

Development Setup

Important: Development uses a virtual environment isolated from your Reticulum installation. This prevents conflicts and allows testing without affecting your production setup.

1. Fork and clone the repository

   git clone https://github.com/YOUR-USERNAME/ble-reticulum.git
   cd ble-reticulum
   

2. Create and activate virtual environment

   python3 -m venv venv
   source venv/bin/activate  # On Linux/macOS
   

3. Install Reticulum (required for tests)

   pip install rns
   

4. Install dependencies (includes runtime and development dependencies)

   pip install -r requirements-dev.txt
   

5. Create package structure (required for imports in tests)

   touch src/RNS/__init__.py
   touch src/RNS/Interfaces/__init__.py
   

6. Run tests to verify setup

   pytest
   

All tests should pass. If you encounter errors, check that you're in the virtual environment and all dependencies are installed.

Development Workflow

1. Create a Branch

Create a feature branch for your work:

git checkout -b feature/your-feature-name

Use descriptive branch names:

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• test/ - Test improvements

2. Make Changes

• Follow existing code style and conventions
• Add tests for new functionality
• Update documentation as needed
• Keep commits focused and atomic

3. Run Tests

Before submitting, ensure all tests pass:

# Run all tests
pytest

# Run with coverage
pytest --cov=src/RNS/Interfaces

# Run specific test file
pytest tests/test_fragmentation.py -v

4. Commit Changes

Use clear, descriptive commit messages:

git commit -m "feat: Add connection retry backoff"
git commit -m "fix: Handle GATT disconnection edge case"
git commit -m "docs: Update configuration examples"

5. Submit Pull Request

1. Push your branch to your fork
2. Open a pull request against the main repository
3. Describe your changes clearly
4. Reference any related issues

Code Style

Python Style

• Follow PEP 8 guidelines
• Maximum line length: 100 characters
• Use meaningful variable names

Code Organization

• Keep functions focused and single-purpose
• Add docstrings to all public functions and classes
• Use type hints where appropriate
• Handle errors gracefully with proper exception handling

Example

def fragment_packet(self, packet: bytes, mtu: int = 185) -> List[bytes]:
    """
    Fragment a packet into BLE-sized chunks.

    Args:
        packet: The packet data to fragment
        mtu: Maximum transmission unit size (default: 185)

    Returns:
        List of packet fragments with headers

    Raises:
        ValueError: If packet is empty or MTU is too small
    """
    if not packet:
        raise ValueError("Cannot fragment empty packet")
    # ... implementation

Testing Guidelines

Writing Tests

• Write tests for all new functionality
• Use descriptive test names: test_fragment_packet_handles_empty_input
• Test both success and failure cases
• Use pytest fixtures for common setup

Test Organization

• Unit tests: Test individual components in isolation
• Integration tests: Test component interactions
• Use mocks for external dependencies (BLE hardware)

Example Test

def test_fragmenter_handles_large_packet():
    """Test that fragmenter correctly splits packets larger than MTU"""
    fragmenter = BLEFragmenter(mtu=185)
    large_packet = b"x" * 500

    fragments = fragmenter.fragment_packet(large_packet)

    assert len(fragments) > 1
    assert all(len(f) <= 185 for f in fragments)

Documentation

Code Documentation

• Add docstrings to all public functions and classes
• Include parameter descriptions and return values
• Document exceptions that may be raised
• Provide usage examples in docstrings

User Documentation

• Update README.md for user-facing changes
• Update examples/ for configuration changes
• Add troubleshooting tips for common issues
• Keep documentation clear and concise

Bug Reports

When reporting bugs, please include:

1. Description: Clear description of the issue
2. Steps to reproduce: Exact steps to trigger the bug
3. Expected behavior: What should happen
4. Actual behavior: What actually happens
5. Environment:
   • OS and version
   • Python version
   • Reticulum version
   • BLE hardware
6. Logs: Relevant log output (use rnsd --verbose)

Example Bug Report

**Bug**: GATT server fails to start on Raspberry Pi Zero W

**Steps to reproduce**:
1. Install on fresh Raspberry Pi Zero W
2. Configure BLE interface in ~/.reticulum/config
3. Run `rnsd --verbose`

**Expected**: GATT server starts and advertises

**Actual**: Error "Failed to register GATT application"

**Environment**:
- OS: Raspberry Pi OS (Debian 11)
- Python: 3.9.2
- Reticulum: 1.0.0
- Hardware: Raspberry Pi Zero W (built-in BLE)

**Logs**:
[2025-10-26 10:15:23] [ERROR] GATT server registration failed
...

Feature Requests

When suggesting features:

1. Use case: Describe the problem you're trying to solve
2. Proposed solution: How you think it should work
3. Alternatives: Other solutions you've considered
4. Impact: Who would benefit from this feature

Review Process

Pull Request Review

Pull requests will be reviewed for:

• Functionality: Does it work as intended?
• Tests: Are there adequate tests?
• Code quality: Is the code clean and maintainable?
• Documentation: Is it properly documented?
• Compatibility: Does it maintain backward compatibility?

Review Timeline

• Small fixes: Usually reviewed within 1-3 days
• New features: May take 5-7 days for thorough review
• Complex changes: May require multiple review rounds

Questions?

If you have questions about contributing:

• Open an issue with the question label
• Check existing issues and pull requests
• Review the documentation in the repository

Code of Conduct

• Be respectful and constructive
• Welcome newcomers and help them learn
• Focus on the code, not the person
• Give and receive feedback gracefully

Thank you for contributing to Reticulum BLE Interface!