Skip to content

Contributing

Jump to bottom
whisprer edited this page Nov 18, 2025 · 1 revision

Contributing

Thank you for considering contributing to Zigbee Analyzer! This document provides guidelines for contributing to the project.

Table of Contents

  1. [Code of Conduct](#code-of-conduct)
  2. [Getting Started](#getting-started)
  3. [Development Setup](#development-setup)
  4. [Contribution Workflow](#contribution-workflow)
  5. [Code Style](#code-style)
  6. [Testing](#testing)
  7. [Documentation](#documentation)
  8. [Pull Request Process](#pull-request-process)

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors regardless of experience level, gender identity, sexual orientation, disability, ethnicity, religion, or other personal characteristics.

Expected Behavior

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints and experiences
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members

Unacceptable Behavior

  • Harassment, trolling, or discriminatory comments
  • Personal or political attacks
  • Public or private harassment
  • Publishing others' private information without permission
  • Other conduct which could reasonably be considered inappropriate

Getting Started

Ways to Contribute

  • Bug Reports: Found a bug? Let us know!
  • Feature Requests: Have an idea? Share it!
  • Code: Fix bugs, add features, improve performance
  • Documentation: Improve docs, add examples, fix typos
  • Hardware Support: Add drivers for new devices
  • Testing: Test on different platforms and hardware
  • Design: Improve UI/UX

Good First Issues

Look for issues labeled good first issue or help wanted:

  • Simple bug fixes
  • Documentation improvements
  • Test additions
  • Minor feature implementations

Development Setup

Prerequisites

# Rust (1.70 or newer)
rustup update stable

# Development tools
rustup component add rustfmt clippy

# Optional: cargo-watch for auto-rebuild
cargo install cargo-watch

Clone and Build

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/zigbee-analyzer.git
cd zigbee-analyzer

# Add upstream remote
git remote add upstream https://github.com/wofl/zigbee-analyzer.git

# Build all crates
cargo build

# Run tests
cargo test --all

# Run linter
cargo clippy --all-targets --all-features

Development Workflow

# Create a feature branch
git checkout -b feature/my-awesome-feature

# Make changes, commit often
git add .
git commit -m "Add feature X"

# Keep your branch up to date
git fetch upstream
git rebase upstream/main

# Push to your fork
git push origin feature/my-awesome-feature

Code Style

Rust Style Guide

We follow the official Rust style guide. Use rustfmt to format code:

# Format all code
cargo fmt --all

# Check formatting without changing files
cargo fmt --all -- --check

Naming Conventions

Types and Traits:

// PascalCase
struct RawPacket { }
trait ZigbeeCapture { }
enum FrameType { }

Functions and Variables:

// snake_case
fn capture_packet() { }
let frame_count = 0;

Constants:

// SCREAMING_SNAKE_CASE
const MAX_PACKET_SIZE: usize = 127;
const SOF: u8 = 0xFE;

Documentation

Public APIs must have doc comments:

/// Captures a single packet from the device.
///
/// This function blocks until a packet is received or a timeout occurs.
///
/// # Errors
///
/// Returns `HalError::Timeout` if no packet is received within the
/// configured timeout period.
///
/// # Examples
///
/// ```
/// let packet = driver.capture_packet().await?;
/// println!("RSSI: {} dBm", packet.rssi);
/// ```
pub async fn capture_packet(&mut self) -> HalResult<RawPacket> {
    // ...
}

Error Handling

Use Result types:

// Good
fn parse_frame(data: &[u8]) -> Result<Frame, ParseError> {
    // ...
}

// Bad
fn parse_frame(data: &[u8]) -> Frame {
    // ...panics on error
}

Provide context in errors:

// Good
Err(HalError::CommunicationError(format!(
    "Failed to write command 0x{:02x}: {}", cmd, e
)))

// Less good
Err(HalError::CommunicationError(e.to_string()))

Comments

Explain the "why", not the "what":

// Good
// Wait 100ms for device to reset, per datasheet section 4.2
tokio::time::sleep(Duration::from_millis(100)).await;

// Less good
// Sleep for 100 milliseconds
tokio::time::sleep(Duration::from_millis(100)).await;

Testing

Test Requirements

All new code should include tests:

  1. Unit tests for individual functions
  2. Integration tests for module interactions
  3. Documentation tests in doc comments
  4. Hardware tests (when applicable, marked with #[ignore])

Writing Tests

Unit tests:

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_frame_parsing() {
        let data = vec![0x41, 0x88, 0x01, 0xCD, 0xAB];
        let frame = parse_mac_frame(&data).unwrap();
        
        assert_eq!(frame.frame_type, FrameType::Data);
        assert_eq!(frame.sequence, 0x01);
    }
    
    #[test]
    fn test_checksum_calculation() {
        let data = vec![0x01, 0x02, 0x03];
        assert_eq!(calculate_fcs(&data), 0x00);
    }
}

Async tests:

#[tokio::test]
async fn test_packet_capture() {
    let mut driver = MockDriver::new();
    let packet = driver.capture_packet().await.unwrap();
    
    assert!(!packet.data.is_empty());
}

Hardware tests (opt-in):

#[tokio::test]
#[ignore] // Only run with --ignored flag
async fn test_real_hardware() {
    let mut driver = CC2531::new().unwrap();
    driver.initialize().await.unwrap();
    // ...
}

Running Tests

# All tests
cargo test --all

# Specific crate
cargo test -p zigbee-core

# With output
cargo test -- --nocapture

# Hardware tests (requires real hardware)
cargo test --all -- --ignored --test-threads=1

# Coverage (requires tarpaulin)
cargo tarpaulin --all --out Html

Benchmarks

For performance-critical code, add benchmarks:

#[bench]
fn bench_packet_parsing(b: &mut Bencher) {
    let data = generate_test_packet();
    
    b.iter(|| {
        parse_mac_frame(&data)
    });
}

Run benchmarks:

cargo bench --all

Documentation

README Files

Each crate should have a README.md with:

  • Brief description
  • Usage examples
  • Key features
  • Dependencies

Doc Comments

All public APIs must have documentation:

/// Brief one-line summary.
///
/// More detailed explanation of what this does,
/// how it works, and when to use it.
///
/// # Arguments
///
/// * `channel` - Channel number (11-26)
///
/// # Returns
///
/// Returns `Ok(())` on success.
///
/// # Errors
///
/// * `HalError::InvalidChannel` - If channel is out of range
/// * `HalError::CommunicationError` - If device communication fails
///
/// # Examples
///
/// ```
/// # use zigbee_hal::traits::ZigbeeCapture;
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let mut driver = CC2531::new()?;
/// driver.set_channel(15).await?;
/// # Ok(())
/// # }
/// ```
pub async fn set_channel(&mut self, channel: u8) -> HalResult<()>

Wiki Pages

When adding major features, update the wiki:

Pull Request Process

Before Submitting

Checklist:

  • Code compiles without warnings
  • All tests pass (cargo test --all)
  • Code is formatted (cargo fmt --all)
  • No clippy warnings (cargo clippy --all-targets)
  • Documentation is updated
  • CHANGELOG.md is updated (if applicable)
  • Commit messages are descriptive

Creating a Pull Request

  1. Push your branch:

    git push origin feature/my-awesome-feature

  2. Open PR on GitHub:

    • Go to your fork on GitHub
    • Click "New Pull Request"
    • Select your branch
    • Fill out the PR template

  3. PR Title Format:

    [Type] Brief description

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Code style (formatting, etc.)
- refactor: Code refactoring
- test: Adding tests
- chore: Maintenance tasks

  4. PR Description Template:

    ## Description
Brief description of changes

## Motivation
Why is this change needed?

## Changes
- Change 1
- Change 2

## Testing
How was this tested?

## Screenshots (if applicable)

## Checklist
- [ ] Tests pass
- [ ] Code is formatted
- [ ] Documentation updated

Review Process

  1. Automated checks run on all PRs:

    • Compilation
    • Tests
    • Linting
    • Coverage

  2. Code review:

    • At least one maintainer reviews
    • Address feedback promptly
    • Update PR as needed

  3. Merge:

    • Once approved, maintainer will merge
    • Squash commits for clean history
    • Delete feature branch after merge

Specific Contribution Guidelines

Adding Hardware Support

See Driver Development for detailed guide.

Quick checklist:

  • Implement ZigbeeCapture trait
  • Add to DriverRegistry
  • Write tests (unit + integration)
  • Document in Hardware Support
  • Provide example usage
  • Include photos/links if possible

Fixing Bugs

  1. Create an issue first (if not already exists)
  2. Reference issue in commits: Fix #123: Description
  3. Add regression test to prevent recurrence
  4. Test on affected platforms

Adding Features

  1. Discuss first in an issue or discussion
  2. Start small - iterative improvements
  3. Maintain backward compatibility when possible
  4. Document thoroughly
  5. Add examples showing new feature

Release Process

(For maintainers)

Version Numbering

We follow [Semantic Versioning](https://semver.org/):

  • Major (1.0.0): Breaking changes
  • Minor (0.1.0): New features, backward compatible
  • Patch (0.0.1): Bug fixes

Release Checklist

  • Update version in all Cargo.toml files
  • Update CHANGELOG.md
  • Run full test suite
  • Update documentation
  • Create git tag
  • Publish to crates.io
  • Create GitHub release

Communication

Channels

  • GitHub Issues: Bug reports, feature requests
  • GitHub Discussions: Questions, ideas, general discussion
  • Pull Requests: Code review, implementation discussion

Response Times

  • Issues: We aim to respond within 48 hours
  • Pull Requests: Initial review within 72 hours
  • Critical bugs: Priority response

Recognition

Contributors are recognized in:

  • CONTRIBUTORS.md file
  • Release notes
  • Project README

Thank you for contributing to Zigbee Analyzer!

Additional Resources

Questions?

If you have questions about contributing:

  1. Check existing issues and discussions
  2. Open a new discussion
  3. Reach out to maintainers

We're here to help! 🎉

Clone this wiki locally