Skip to main content

Contributing to B.R.I.O.S.

Thank you for considering contributing to B.R.I.O.S.! This guide provides everything you need to get started.

How Can I Contribute?​

Reporting Bugs​

Before submitting a bug report:

  1. Check the existing issues.
  2. Verify the bug exists in the latest version.
  3. Collect information about your environment.

When submitting a bug report, include:

  • Clear, descriptive title
  • Steps to reproduce the issue
  • Expected vs. actual behavior
  • Screenshots if applicable
  • Environment details (macOS version, Python version, etc.)
  • Log files from ~/.brios/.ble_monitor.log if available

Suggesting Enhancements​

  1. Check if the enhancement has already been suggested.
  2. Determine which part of the project your suggestion relates to.
  3. Consider whether it fits the project's scope and goals.

Code Contributions​

We welcome contributions in:

  • Bug fixes
  • New features
  • Performance improvements
  • Documentation improvements
  • Test coverage expansion
  • Code refactoring

Development Setup​

1. Fork and Clone​

git clone https://github.com/YOUR_USERNAME/B.R.I.O.S..git
cd B.R.I.O.S.

2. Create Virtual Environment​

python3 -m venv env
source env/bin/activate

3. Install Development Dependencies​

pip install -r requirements/dev.txt

4. Create a Feature Branch​

Branch names must follow Conventional Commits naming:

git checkout -b feat/add-multi-device-support
git checkout -b fix/scanner-empty-name
git checkout -b docs/update-installation-guide
git checkout -b refactor/simplify-config-loader
git checkout -b test/add-monitor-edge-cases
git checkout -b chore/update-dependencies
PrefixUse For
feat/New features
fix/Bug fixes
docs/Documentation changes
style/Code style / formatting
refactor/Code restructuring (no behavior change)
test/Adding or updating tests
chore/Maintenance tasks, dependencies

Coding Standards​

Python Style​

B.R.I.O.S. follows PEP 8 with Google-style modifications via Pyink:

# Format all code
pyink .

# Or use the Makefile
make format

Rules​

RuleValue
Line length80 characters
Indentation4 spaces (no tabs)
ImportsOrganized: stdlib → third-party → local
DocstringsGoogle-style for all public functions/classes
Type hintsRequired for all function signatures

Example​

def calculate_distance(rssi: float, tx_power: int, path_loss: float) -> float:
    """Calculates distance using Log-Distance Path Loss Model.

    Args:
        rssi: Received Signal Strength Indicator in dBm.
        tx_power: Calibrated signal strength at 1 meter.
        path_loss: Environmental path loss exponent.

    Returns:
        Estimated distance in meters. Returns -1.0 for invalid RSSI.
    """
    if rssi == 0:
        return -1.0
    return 10 ** ((tx_power - rssi) / (10 * path_loss))

Type Checking​

mypy brios/

Testing Requirements​

  • Minimum coverage: 90%
  • Target coverage: 100%
  • All new code must include tests
# Run tests
pytest

# Run with coverage
pytest --cov=brios --cov-report=term-missing

See the Testing Guide for detailed information.

Pull Request Process​

Before Submitting​

  • Update your branch with latest main
  • Run all tests (pytest)
  • Format code (pyink .)
  • Run type checking (mypy brios/)
  • Update documentation if needed
  • Add tests for new features

Creating a Pull Request​

  1. Push your branch: git push origin feature/your-feature-name
  2. Open a PR on GitHub with a clear title and description
  3. Link related issues using Fixes #123 or Closes #456

Review Process​

  1. Automated checks must pass (formatting, type checking, tests, security audit)
  2. Code review — At least one maintainer approval required
  3. Revisions — Address review feedback promptly

Commit Message Guidelines​

Format​

<type>(<scope>): <subject>

Types​

TypeDescription
featNew feature
fixBug fix
docsDocumentation only
styleCode style (formatting, no logic change)
refactorCode restructuring
testAdding or updating tests
choreMaintenance tasks

Examples​

git commit -m "feat(monitor): add multi-device support"
git commit -m "fix(scanner): handle empty device names correctly"
git commit -m "docs(readme): update installation instructions"

Development Workflow​

# 1. Create feature branch
git checkout -b feature/awesome-feature

# 2. Make changes and test
pytest
pyink .
mypy brios/

# 3. Commit
git add .
git commit -m "feat: add awesome feature"

# 4. Push and open PR
git push origin feature/awesome-feature

Makefile Commands​

make format                        # Format code with Pyink
make run ARGS="--scanner 15 -m"    # Run with arguments
make ble-run ARGS="--target-mac -v" # Format + run
make check                         # Run MyPy type checking

Questions?​