docs: add comprehensive CONTRIBUTING.md for GhostArmyIntel collaboration

Created detailed contributor guide including: **Join Process:** - Step-by-step onboarding (accept invite → clone → setup → contribute) - Current contributors: leetcrypt (admin), Ringmast4r (invited) - GhostArmyIntel organization integration options **Collaboration Workflows:** - Option 1: Transfer repo to GhostArmyIntel organization (recommended) - Option 2: Fork to organization (independent development) - Option 3: Direct collaborator access (current setup) **Development Guide:** - Codebase structure walkthrough - Git workflow (feature branches, PRs, commit conventions) - Testing procedures (unit tests, benchmarks) - Priority tasks from REAL_CAPTURE_ANALYSIS.md **Quick Start Tasks:** - Add missing protocols (Acurite 02077M, GE Doorbell, Holtek HT12X) - Implement decoded .sub file support (Priority 1 - fixes 45% failures) - Improve real signal robustness (packet segmentation, noise tolerance) **GhostArmyIntel Integration:** - Links to related projects (wardriving-converter, WiGLE-Vault, OUI-Master-Database) - Organization transfer instructions - Fork workflow for org-owned development Designed to onboard Ringmast4r and GhostArmyIntel team members with complete context on project status, architecture, and contribution paths. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-16 12:49:39 -08:00
parent 621734fa0a
commit 422a1e1d2e
1 changed files with 429 additions and 0 deletions
@@ -0,0 +1,429 @@
 # Contributing to GigLez - IoT RF Device Mapping Platform
 **Welcome!** We're building a Wigle-style platform for Sub-GHz RF device mapping. This guide will help you join the project and start contributing.
 ---
 ## 🏛️ Project Overview
 **GigLez** is an open-source crowdsourced platform for mapping IoT RF devices (300-928 MHz). Think "Wigle.net for garage doors, weather stations, and doorbells."
 **Key Features:**
 - 6-component RF signature matching engine
 - 299 protocol database (RTL_433 imported)
 - GPS validation & privacy features
 - Real-world benchmarking infrastructure
 - Support for Flipper Zero, RTL-SDR, HackRF captures
 **Current Status:**
 - ✅ Core identification engine complete
 - ✅ 56 unit tests passing
 - ⚠️ 33% synthetic accuracy, 0% real-world (documented gap analysis)
 - 📊 Benchmarking & calibration in progress
 ---
 ## 👥 Current Contributors
 ### Core Team
 - **leetcrypt** - Repository owner, core developer (admin access)
 - **Ringmast4r** - Invited collaborator (write access) - *Pending acceptance*
 ### Organizations
 - **GhostArmyIntel** - Organization for wardriving & RF intelligence projects
  - Projects: wardriving-converter, WiGLE-Vault, OUI-Master-Database
 ---
 ## 🚀 How to Join the Project
 ### Step 1: Accept Your Invitation
 If you've been invited as a collaborator:
 1. **Check your email** for invitation from GitHub
 2. **Or visit:** https://github.com/notifications
 3. **Accept the invitation** to join `leetcrypt/giglez`
 4. You'll receive **write access** (push, pull, create branches/PRs)
 **Pending Invitations:**
 - Ringmast4r (invited 2026-02-16)
 ### Step 2: Clone the Repository
 ```bash
 # Clone the repo
 git clone https://github.com/leetcrypt/giglez.git
 cd giglez
 # Verify you have access
 git remote -v
 ```
 ### Step 3: Set Up Your Environment
 #### Option A: Python Virtual Environment
 ```bash
 # Create virtual environment
 python3 -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate
 # Install dependencies (if requirements.txt exists)
 pip install -r requirements.txt
 # Run tests to verify setup
 python -m pytest tests/ -v
 ```
 #### Option B: Development with Existing Tools
 If you already have Python 3.10+ and pytest:
 ```bash
 # Just run the tests
 cd /path/to/giglez
 python -m pytest tests/ -v
 ```
 ### Step 4: Understand the Codebase
 **Key Directories:**
 ```
 giglez/
 ├── src/
 │   ├── matcher/           # RF device identification engine
 │   │   ├── device_identifier.py      # Unified API (iteration 6/6)
 │   │   ├── pattern_decoder.py        # Multi-factor scoring
 │   │   ├── timing_analyzer.py        # Pulse timing extraction
 │   │   ├── preamble_detector.py      # Sync pattern detection
 │   │   ├── frequency_fingerprint.py  # ISM band classification
 │   │   ├── statistical_classifier.py # Bayesian scoring
 │   │   └── protocol_database.py      # 299 protocol signatures
 │   ├── parser/
 │   │   └── sub_parser.py             # Flipper .sub file parser
 │   └── gps/
 │       └── validator.py              # GPS validation & privacy
 ├── tests/
 │   ├── unit/                         # 56 unit tests
 │   ├── benchmark/                    # Synthetic signal testing
 │   └── real_captures/                # Real Flipper Zero files
 ├── scripts/
 │   ├── benchmark.py                  # Accuracy benchmarking
 │   └── benchmark_real.py             # Real-world testing
 └── docs/
    ├── REAL_CAPTURE_ANALYSIS.md      # 0% accuracy gap analysis
    └── WARDRIVER_ONBOARDING.md       # RF community survey
 ```
 **Read First:**
 1. `CLAUDE.md` - Project status & architecture
 2. `docs/REAL_CAPTURE_ANALYSIS.md` - Critical findings on real-world performance
 3. `docs/WARDRIVER_ONBOARDING.md` - Data format requirements
 ### Step 5: Make Your First Contribution
 #### Quick Start Tasks (Good First Issues)
 **1. Add Missing Protocols** (Priority 2 fix - 27% of failures)
 - Add Acurite 02077M to protocol database
 - Add GE Doorbell 19297
 - Add Byron DB421E
 - Add Holtek HT12X (fan/LED remotes)
 **2. Test Real Captures**
 - Download more real .sub files from UberGuidoZ/Flipper
 - Run `scripts/benchmark_real.py`
 - Document which protocols work/fail
 **3. Improve Documentation**
 - Add examples to CONTRIBUTING.md
 - Create protocol database contribution guide
 - Document how to add new signal types
 **4. Fix Decoded .sub File Support** (Priority 1 fix - 45% of failures)
 - Implement parser for decoded Flipper files
 - Extract Protocol, Bit, Key, TE fields
 - Match by protocol name + timing element
 ---
 ## 🔄 Git Workflow
 ### Standard Development Workflow
 ```bash
 # 1. Create feature branch
 git checkout -b feature/your-feature-name
 # 2. Make changes and commit
 git add .
 git commit -m "feat: add Acurite 02077M protocol support"
 # 3. Push to GitHub
 git push origin feature/your-feature-name
 # 4. Create Pull Request on GitHub
 # Visit: https://github.com/leetcrypt/giglez/pulls
 # Click "New Pull Request"
 ```
 ### Commit Message Convention
 Follow conventional commits:
 ```
 feat: add new protocol support for Holtek HT12X
 fix: correct timing ratio calculation for Oregon Scientific
 docs: update CONTRIBUTING.md with fork workflow
 test: add unit tests for decoded .sub file parsing
 refactor: optimize preamble detection algorithm
 ```
 ### Branch Naming
 - `feature/protocol-xyz` - New protocol additions
 - `fix/timing-accuracy` - Bug fixes
 - `docs/contributing-guide` - Documentation
 - `test/real-captures` - Test improvements
 ---
 ## 🏗️ For GhostArmyIntel Organization
 ### Option 1: Transfer Repository to Organization (Recommended)
 **Requires:** GhostArmyIntel organization admin to accept transfer
 **Process:**
 1. Repository owner (leetcrypt) initiates transfer:
   ```bash
   gh api -X POST /repos/leetcrypt/giglez/transfer \
     -f new_owner=GhostArmyIntel
   ```
 2. GhostArmyIntel org admin accepts transfer at:
   https://github.com/settings/repositories
 3. Repository becomes: `GhostArmyIntel/giglez`
 4. leetcrypt is re-added as collaborator
 **Pros:**
 - Organization owns the repo
 - Professional branding
 - Team can manage collaborators
 - Fits with wardriving-converter, WiGLE-Vault projects
 **Cons:**
 - Requires org admin permission
 - URL changes (redirect is automatic)
 ### Option 2: Fork to Organization
 **Process:**
 1. GhostArmyIntel member visits: https://github.com/leetcrypt/giglez
 2. Click "Fork" button
 3. Select "GhostArmyIntel" as owner
 4. Fork created at: `GhostArmyIntel/giglez`
 **Workflow:**
 ```bash
 # Clone the fork
 git clone https://github.com/GhostArmyIntel/giglez.git
 cd giglez
 # Add upstream remote (original repo)
 git remote add upstream https://github.com/leetcrypt/giglez.git
 # Sync with upstream
 git fetch upstream
 git merge upstream/main
 ```
 **Pros:**
 - Independent development
 - Can create org-specific features
 - Proper fork relationship
 **Cons:**
 - Two separate repositories
 - Need to sync regularly
 ### Option 3: Collaborator Access (Current Setup)
 **Process:**
 1. Ringmast4r accepts invitation to leetcrypt/giglez
 2. Works directly on shared repository
 3. Creates branches and PRs
 **Pros:**
 - Simple, immediate access
 - Single source of truth
 **Cons:**
 - Not under GhostArmyIntel organization
 ---
 ## 📊 Current Priority Tasks
 Based on `docs/REAL_CAPTURE_ANALYSIS.md`:
 ### Priority 1: Decoded .sub File Support (Fixes 45% of failures)
 **Impact:** 5/11 real captures failed because they're decoded, not RAW
 **Task:**
 ```python
 # Implement in src/parser/sub_parser.py
 def parse_decoded_sub_file(filepath):
    """Parse decoded Flipper .sub files"""
    # Extract: Protocol, Bit, Key, TE
    # Match by protocol name + timing element
    # Return SignalMetadata with is_decoded=True
 ```
 ### Priority 2: Add Missing Protocols (Fixes 27% of failures)
 **Needed:**
 - Acurite 02077M (weather station)
 - GE Doorbell 19297
 - Byron DB421E
 - Holtek HT12X (LED/fan remotes)
 - LiftMaster (generic 433 MHz)
 **Task:**
 Add to `src/matcher/protocol_database.py`:
 ```python
 Protocol(
    name="Acurite 02077M",
    category="weather_sensor",
    frequency=433920000,
    short_pulse_us=1000,
    long_pulse_us=2000,
    # ... etc
 )
 ```
 ### Priority 3: Improve Real Signal Robustness (Fixes 27% of failures)
 **Issues:**
 - Multi-packet transmissions (131 pulses vs 40 bits)
 - Signal noise beyond 15% tolerance
 **Tasks:**
 - Implement packet segmentation
 - Increase jitter tolerance from 15% → 25%
 - Add repetition detection
 ---
 ## 🧪 Testing Your Changes
 ### Run All Tests
 ```bash
 # All unit tests
 pytest tests/ -v
 # Specific test file
 pytest tests/unit/test_timing_analyzer.py -v
 # With coverage
 pytest tests/ --cov=src --cov-report=html
 ```
 ### Run Benchmarks
 ```bash
 # Synthetic signal benchmark
 python scripts/benchmark.py
 # Real-world captures benchmark
 python scripts/benchmark_real.py
 ```
 ### Expected Output
 ```
 REAL-WORLD BENCHMARK SUMMARY
 ═══════════════════════════════
 Total Tests: 11
 TOP-K ACCURACY:
  Top-1: 0.0% (0/11)   # Target: improve this!
  Top-3: 0.0% (0/11)
 ```
 ---
 ## 📞 Communication & Coordination
 ### GitHub Discussions
 Use GitHub Issues for:
 - Bug reports
 - Feature requests
 - Protocol addition proposals
 - Questions about implementation
 ### Pull Request Reviews
 - Tag @leetcrypt for code review
 - Tag @Ringmast4r for wardriving expertise
 - Wait for approval before merging
 ### Project Board (Coming Soon)
 Track work on GitHub Projects:
 - To Do: Priority tasks from REAL_CAPTURE_ANALYSIS.md
 - In Progress: Current work
 - Done: Completed features
 ---
 ## 🎯 Long-Term Vision
 ### Phase 1 (Current): Core Identification Engine
 - ✅ Multi-factor scoring
 - ✅ Protocol database (299 protocols)
 - ⚠️ Real-world accuracy (in progress)
 ### Phase 2: Web Platform
 - Upload interface (drag .sub files + GPS)
 - Interactive map (Leaflet.js)
 - Device database browser
 ### Phase 3: Community Features
 - Manual device ID submission
 - Photo uploads
 - Voting/verification system
 - Leaderboards
 ### Phase 4: Multi-Format Support
 - rtl_433 JSON import
 - URH .complex files
 - GPX track parsing
 - Batch upload API
 ---
 ## 📄 License
 MIT License - See LICENSE file
 ---
 ## 🤝 Code of Conduct
 - Be respectful and professional
 - Provide constructive feedback
 - Help newcomers learn
 - Document your changes
 - Test before pushing
 ---
 ## ❓ Questions?
 **GitHub Issues:** https://github.com/leetcrypt/giglez/issues
 **Repository:** https://github.com/leetcrypt/giglez
 **Related GhostArmyIntel Projects:**
 - wardriving-converter: https://github.com/GhostArmyIntel/wardriving-converter
 - WiGLE-Vault: https://github.com/GhostArmyIntel/WiGLE-Vault
 - OUI-Master-Database: https://github.com/GhostArmyIntel/OUI-Master-Database
 ---
 *"A Ringmast4r project honoring the WWII Ghost Army — blending art, code, and strategy into modern open-source signalcraft."*
 **Last Updated:** 2026-02-16