326 lines
8.9 KiB
Markdown
326 lines
8.9 KiB
Markdown
# 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](docs/development.md) 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](https://github.com/your-org/NowYouSeeMe/issues)
|
|
2. **Reproduce the Issue**: Ensure you can consistently reproduce the problem
|
|
3. **Check Documentation**: Verify the issue isn't covered in the [documentation](docs/)
|
|
|
|
### Bug Report Template
|
|
|
|
```markdown
|
|
**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
|
|
|
|
```markdown
|
|
**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](https://www.python.org/dev/peps/pep-0008/) 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
|
|
|
|
```python
|
|
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](https://google.github.io/styleguide/cppguide.html)
|
|
- Use meaningful variable and function names
|
|
- Add comments for complex algorithms
|
|
- Include error handling and logging
|
|
|
|
```cpp
|
|
/**
|
|
* @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
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
```python
|
|
# 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](https://semver.org/):
|
|
- **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](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](LICENSE).
|
|
|
|
---
|
|
|
|
Thank you for contributing to NowYouSeeMe! Your contributions help make this project better for everyone. |