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

Creating Releases (Maintainers Only)

This section is for project maintainers who have push access to create official releases.

Release Process

Releases are automated through GitHub Actions. The workflow validates everything and creates the release when you push a version tag.

Steps to create a release:

1. Ensure all changes are merged to main

   git checkout main
   git pull origin main
   

2. Update version in pyproject.toml

   # Edit pyproject.toml
   version = "0.2.3"  # Update to new version
   

3. Update CHANGELOG.md

   • Move changes from [Unreleased] section to new version section
   • Add release date
   • Example:

     ## [0.2.3] - 2025-11-08
     ### Added
     - New feature X
     ### Fixed
     - Bug Y
     

4. Commit version bump

   git add pyproject.toml CHANGELOG.md
   git commit -m "chore: Bump version to 0.2.3"
   git push origin main
   

5. Create and push tag

   git tag v0.2.3
   git push origin v0.2.3
   

6. Wait for automation

   • GitHub Actions will automatically:
     • Validate version consistency
     • Run full test suite
     • Extract release notes from CHANGELOG.md
     • Create GitHub release
     • Upload artifacts (install.sh, checksums, source archive)
   • Monitor progress at: https://github.com/torlando-tech/ble-reticulum/actions

7. Verify release

   • Check release page: https://github.com/torlando-tech/ble-reticulum/releases
   • Verify all assets are present
   • Test installation from release

Version Numbering

Follow semantic versioning (MAJOR.MINOR.PATCH):

• Major (X.0.0): Breaking changes requiring all nodes to upgrade
  • Example: Protocol changes incompatible with older versions
• Minor (0.X.0): New features, backward-compatible improvements
  • Example: New configuration options, performance improvements
• Patch (0.0.X): Bug fixes, documentation updates
  • Example: Fix connection timeout, update README

Release Checklist

Before creating a release, verify:

• All planned features/fixes are merged to main
• Tests pass on main branch
• CHANGELOG.md is updated with all changes
• Version in pyproject.toml matches planned release
• Documentation is up to date (README, protocol docs)
• No known critical bugs
• Breaking changes are clearly documented

Release Contents

Each release automatically includes:

• Source archives (tar.gz, zip) - auto-generated by GitHub
• install.sh - standalone installer script
• config_example.toml - example configuration
• SHA256SUMS.txt - checksums for all assets
• Release notes - extracted from CHANGELOG.md

Troubleshooting Releases

Release validation fails:

• Check that pyproject.toml version matches tag (v0.2.3 → 0.2.3)
• Verify CHANGELOG.md has entry for the version
• Ensure tag is on main branch

Tests fail:

• Release workflow reuses test.yml
• Check test results in GitHub Actions
• Fix issues, commit, and create new tag with patch version

Need to re-create a release:

1. Delete the tag locally: git tag -d v0.2.3
2. Delete the tag remotely: git push origin :refs/tags/v0.2.3
3. Delete the GitHub release (if created)
4. Fix issues, update version/tag, and retry

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!