Contributing

Help improve NetScan! We welcome contributions of all kinds.

Ways to Contribute

  • 🐛 Report bugs — Open an issue with details
  • 💡 Suggest features — Share your ideas
  • 📖 Improve docs — Fix typos, add examples
  • 🔧 Submit code — Bug fixes, new features
  • 🧪 Test — Test on different platforms

Development Setup

# Clone repo
git clone https://github.com/G1A1B1E/NetScan.git
cd NetScan

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

# Install dev dependencies
pip3 install -r requirements-dev.txt

# Run tests
python3 -m pytest tests/

Code Style

  • Python: PEP 8, type hints encouraged
  • Bash: ShellCheck clean
  • Rust: cargo fmt and cargo clippy
# Format Python
black helpers/
isort helpers/

# Check Bash
shellcheck lib/*.sh

# Format Rust
cd rust_helpers && cargo fmt

Pull Request Process

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/xyz)
  3. Make your changes
  4. Run tests (python3 -m pytest)
  5. Commit (git commit -m 'Add xyz feature')
  6. Push (git push origin feature/xyz)
  7. Open Pull Request

Project Structure

NetScan/
├── netscan              # Main entry point
├── lib/                 # Bash libraries
│   ├── scanner.sh
│   ├── mac_lookup.sh
│   └── utils.sh
├── helpers/             # Python modules
│   ├── mac_lookup.py
│   ├── scanner.py
│   ├── oui_parser.py
│   └── fast_core.py
├── rust_helpers/        # Optional Rust module
│   ├── Cargo.toml
│   └── src/
├── docs/                # Documentation
└── tests/               # Test suite

Testing

# Run all tests
python3 -m pytest

# Run specific test
python3 -m pytest tests/test_mac_lookup.py

# With coverage
python3 -m pytest --cov=helpers

Reporting Issues

Include:

  • Operating system and version
  • Python version (python3 --version)
  • NetScan version (netscan --version)
  • Full error message
  • Steps to reproduce

License

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

Code of Conduct

Be respectful, inclusive, and constructive. See CODE_OF_CONDUCT.md