NYSM-NYD/CONTRIBUTING.md

Contributing to NowYouSeeMe

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

🤝 How to Contribute

We welcome contributions from the community in many forms:

• Bug Reports: Help us identify and fix issues
• Feature Requests: Suggest new features and improvements
• Code Contributions: Submit pull requests with code changes
• Documentation: Improve or add to our documentation
• Testing: Help test the system and report issues
• Community Support: Help other users on GitHub and Discord

📋 Before You Start

Prerequisites

• Familiarity with Python and C++
• Understanding of computer vision and signal processing concepts
• Git and GitHub workflow knowledge
• Basic understanding of SLAM and sensor fusion

Development Environment

1. Fork the Repository: Create your own fork of the project
2. Clone Your Fork: git clone https://github.com/your-username/NowYouSeeMe.git
3. Set Up Environment: Follow the Development Setup guide
4. Create a Branch: git checkout -b feature/your-feature-name

🐛 Reporting Bugs

Before Reporting

1. Check Existing Issues: Search for similar issues in the GitHub Issues
2. Reproduce the Issue: Ensure you can consistently reproduce the problem
3. Check Documentation: Verify the issue isn't covered in the documentation

Bug Report Template

**Bug Description**
A clear description of what the bug is.

**Steps to Reproduce**
1. Go to '...'
2. Click on '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python Version: [e.g., 3.9]
- CUDA Version: [e.g., 11.6]
- Hardware: [e.g., Intel 5300 WiFi card]

**Additional Context**
Any other context, logs, or screenshots.

💡 Suggesting Features

Feature Request Template

**Feature Description**
A clear description of the feature you'd like to see.

**Use Case**
How would this feature be used? What problem does it solve?

**Proposed Implementation**
Any ideas on how this could be implemented?

**Alternatives Considered**
What other solutions have you considered?

**Additional Context**
Any other context or examples.

🔧 Code Contributions

Code Style Guidelines

Python

• Follow PEP 8 style guide
• Use type hints for function parameters and return values
• Write docstrings for all public functions and classes
• Keep functions focused and under 50 lines when possible

def process_csi_data(csi_packet: CSIPacket) -> CIRResult:
    """
    Process CSI packet and convert to Channel Impulse Response.
    
    Args:
        csi_packet: CSI packet containing subcarrier data
        
    Returns:
        CIRResult containing delay and amplitude information
        
    Raises:
        ValueError: If CSI data is invalid
    """
    # Implementation here
    pass

C++

• Follow Google C++ Style Guide
• Use meaningful variable and function names
• Add comments for complex algorithms
• Include error handling and logging

/**
 * @brief Process CSI data and convert to CIR
 * @param csi_data Input CSI data
 * @return CIR result with delay and amplitude
 * @throws std::runtime_error if data is invalid
 */
CIRResult processCSIData(const CSIData& csi_data) {
    // Implementation here
}

Testing Requirements

• Unit Tests: Write tests for new functionality
• Integration Tests: Test component interactions
• Performance Tests: For performance-critical code
• Documentation: Update relevant documentation

Pull Request Process

1. Create Feature Branch: git checkout -b feature/your-feature
2. Make Changes: Implement your feature or fix
3. Write Tests: Add tests for new functionality
4. Update Documentation: Update relevant docs
5. Run Tests: Ensure all tests pass
6. Commit Changes: Use clear commit messages
7. Push to Fork: git push origin feature/your-feature
8. Create Pull Request: Use the PR template below

Pull Request Template

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Refactoring

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Performance tests pass
- [ ] Manual testing completed

## Documentation
- [ ] Updated relevant documentation
- [ ] Added inline comments where needed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Code is commented
- [ ] Tests added/updated
- [ ] Documentation updated

📚 Documentation Contributions

Documentation Guidelines

• Clear and Concise: Write in clear, simple language
• Code Examples: Include working code examples
• Screenshots: Add visual guides where helpful
• Cross-References: Link to related documentation
• Version Information: Mark version-specific content

Documentation Structure

docs/
├── README.md                 # Main documentation index
├── installation.md           # Installation guide
├── quickstart.md            # Quick start guide
├── api/                     # API documentation
│   ├── README.md
│   ├── ingestion.md
│   └── ...
└── ...

🧪 Testing Guidelines

Test Types

1. Unit Tests: Test individual functions and classes
2. Integration Tests: Test component interactions
3. Performance Tests: Test timing and resource usage
4. End-to-End Tests: Test complete workflows

Test Structure

# tests/test_cir_converter.py
import pytest
from src.rf_slam.cir_converter import CIRConverter, CIRConfig

class TestCIRConverter:
    def test_csi_to_cir_conversion(self):
        """Test CSI to CIR conversion with synthetic data."""
        config = CIRConfig()
        converter = CIRConverter(config)
        
        # Test implementation
        csi_data = generate_synthetic_csi()
        result = converter.process_csi_packet(csi_data)
        
        assert result is not None
        assert "cir" in result
        assert "peaks" in result

🚀 Release Process

Version Numbers

We follow Semantic Versioning:

• MAJOR: Incompatible API changes
• MINOR: New functionality (backward compatible)
• PATCH: Bug fixes (backward compatible)

Release Checklist

• All tests pass
• Documentation updated
• Changelog updated
• Version numbers updated
• Release notes written
• Binaries built and tested

🏷️ Labels and Milestones

Issue Labels

• bug: Something isn't working
• enhancement: New feature or request
• documentation: Documentation improvements
• good first issue: Good for newcomers
• help wanted: Extra attention needed
• priority: high: High priority issues
• priority: low: Low priority issues

Milestones

• v1.1.0: Next minor release
• v1.2.0: Future features
• Backlog: Long-term ideas

📞 Getting Help

Communication Channels

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For questions and general discussion
• Discord: For real-time chat and support
• Email: For private or sensitive issues

Mentorship

• New Contributors: We're happy to mentor new contributors
• Code Reviews: We provide detailed feedback on all contributions
• Documentation: We help improve documentation contributions

🎯 Contribution Areas

High Priority

• Performance Optimization: Improve system latency and throughput
• Robustness: Improve error handling and recovery
• Documentation: Expand and improve documentation
• Testing: Add more comprehensive tests

Medium Priority

• New Features: Add new capabilities and algorithms
• UI/UX: Improve user interfaces and experience
• Integration: Better integration with external tools
• Monitoring: Enhanced system monitoring and diagnostics

Low Priority

• Experimental Features: Research and experimental algorithms
• Nice-to-Have: Quality of life improvements
• Optimization: Minor performance improvements

🙏 Recognition

We recognize and appreciate all contributions:

• Contributors: Listed in the CONTRIBUTORS.md file
• Code Contributors: Automatically listed in GitHub
• Documentation Contributors: Acknowledged in documentation
• Community Support: Recognized in release notes

📄 License

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

---

Thank you for contributing to NowYouSeeMe! Your contributions help make this project better for everyone.