webdrop-bridge/CONTRIBUTING.md

# Contributing to WebDrop Bridge

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the WebDrop Bridge project.

## Code of Conduct

Please be respectful and constructive in all interactions. We're building a welcoming community for developers of all experience levels.

## Getting Started

### Prerequisites
- Python 3.10+
- Git
- Familiarity with Qt/PySide6 or willingness to learn

### Setup Development Environment

```bash
# Fork and clone the repository
git clone https://github.com/yourusername/webdrop-bridge.git
cd webdrop-bridge

# Create virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install
```

## Development Workflow

### 1. Create a Feature Branch

```bash
git checkout -b feature/your-feature-name
```

Use descriptive names:
- `feature/drag-performance-optimization`
- `bugfix/path-validation-windows`
- `docs/add-architecture-guide`

### 2. Write Tests First (TDD)

```bash
# Create test file
touch tests/unit/test_my_feature.py

# Write failing tests
pytest tests/unit/test_my_feature.py

# Implement feature
# Re-run tests until passing
```

### 3. Implement Your Feature

```bash
# Follow the project structure
src/webdrop_bridge/
├── core/       # Core logic
├── ui/         # UI components
└── utils/      # Utilities
```

### 4. Code Quality Checks

```bash
# Format code
tox -e format

# Run linting
tox -e lint

# Type checking
tox -e type

# Full test suite
pytest --cov

# All checks
tox
```

### 5. Write Documentation

- Add docstrings to all functions/classes
- Update README.md if adding features
- Add examples for new APIs

### 6. Commit and Push

```bash
# Commit with meaningful message
git commit -m "feat: add feature description

- Detailed explanation of changes
- Bullet points for key changes
- References to related issues"

# Push to your fork
git push origin feature/your-feature-name
```

### 7. Submit Pull Request

- Use clear, descriptive title
- Reference related issues (#123)
- Describe changes and testing approach
- Include screenshots/videos if UI-related

## Code Style

### Python Style Guide

Follow PEP 8, enforced by Black and Ruff:

```python
# Good
def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
    """Validate path against allowed roots."""
    resolved = path.resolve()
    return any(is_relative_to(resolved, root) for root in allowed_roots)


# Bad
def validate_path(path,allowed_roots):
    resolved=path.resolve()
    return any(is_relative_to(resolved,root)for root in allowed_roots)
```

### Type Hints

Always use type hints:

```python
from typing import Optional, List
from pathlib import Path

def process_files(files: List[Path], validate: bool = True) -> Optional[int]:
    """Process a list of files."""
    pass
```

### Docstrings

Use Google-style docstrings:

```python
def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
    """Validate that path is within allowed roots.
    
    Args:
        path: File path to validate
        allowed_roots: List of allowed root directories
        
    Returns:
        True if path is valid, False otherwise
        
    Raises:
        ValueError: If path cannot be resolved
    """
```

## Testing Guidelines

### Unit Tests

Test individual functions/classes in isolation:

```python
# tests/unit/test_validator.py
import pytest
from webdrop_bridge.core.validator import PathValidator
from pathlib import Path

@pytest.fixture
def validator():
    allowed_roots = [Path("C:/Users/Public")]
    return PathValidator(allowed_roots)

def test_valid_path(validator):
    """Test that valid paths are accepted."""
    path = Path("C:/Users/Public/Documents/file.txt")
    assert validator.is_allowed(path)

def test_invalid_path(validator):
    """Test that invalid paths are rejected."""
    path = Path("C:/Windows/System32/file.txt")
    assert not validator.is_allowed(path)
```

### Integration Tests

Test components working together:

```python
# tests/integration/test_drag_workflow.py
def test_complete_drag_workflow(temp_test_dir):
    """Test complete drag-and-drop workflow."""
    # Setup
    test_file = temp_test_dir / "test.txt"
    test_file.write_text("content")
    
    # Execute
    validator = PathValidator([temp_test_dir])
    result = validator.is_valid_file(test_file)
    
    # Verify
    assert result is True
```

### Test Coverage

- Aim for 80%+ code coverage
- All public APIs must have tests
- Test both happy path and error cases

```bash
# Check coverage
pytest --cov=src/webdrop_bridge --cov-report=html

# View detailed report
open htmlcov/index.html  # macOS
start htmlcov\index.html # Windows
```

## Platform-Specific Development

### Windows

```bash
# For Windows-specific tests
pytest -m windows

# Build Windows installer
python build/scripts/build_windows.py
```

### macOS

```bash
# For macOS-specific tests
pytest -m macos

# Build macOS DMG
bash build/scripts/build_macos.sh
```

## Common Issues

### Import Errors

Ensure project is in PYTHONPATH:

```bash
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"  # macOS/Linux
set PYTHONPATH=%PYTHONPATH%;%cd%\src  # Windows
```

Or install in development mode:

```bash
pip install -e .
```

### PySide6 Installation Issues

```bash
# Force reinstall
pip install --force-reinstall --no-cache-dir PySide6

# On macOS with Apple Silicon
pip install PySide6 --target $PYTHON_ENV
```

### Test Failures in CI but Not Locally

- Check Python version: `python --version`
- Verify all dependencies: `pip list`
- Clear cache: `rm -rf .pytest_cache build/`
- Try clean venv: `rm -rf venv && python -m venv venv`

## Documentation

### API Documentation

Docstrings are automatically converted to HTML:

```bash
tox -e docs

# View documentation
open docs/_build/html/index.html  # macOS
start docs\_build\html\index.html # Windows
```

### Writing Documentation

- Use Markdown for guides
- Include code examples
- Add screenshots for UI features
- Keep language clear and concise

## Writing Integration Tests

Integration tests should cover workflows across multiple components. See [tests/integration/test_update_flow.py](tests/integration/test_update_flow.py) for an example covering the update system.

## Release Process

### Version Numbering

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

- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes

Example: `1.2.3` (Major.Minor.Patch)

### Creating a Release

1. Update version in:
   - `pyproject.toml`
   - `src/webdrop_bridge/__init__.py`

2. Update CHANGELOG.md

3. Create git tag:
   ```bash
   git tag -a v1.2.3 -m "Release version 1.2.3"
   git push origin v1.2.3
   ```

4. GitHub Actions will automatically build installers

## Getting Help

- **Issues**: Report bugs or request features
- **Discussions**: Ask questions or discuss ideas
- **Documentation**: Check docs/ folder
- **Code Examples**: Look at tests/ folder

## Review Process

All pull requests require:

- ✅ Tests pass (100% on target platforms)
- ✅ Code review approved
- ✅ No lint/type warnings
- ✅ Documentation updated
- ✅ Coverage maintained or improved

## Recognition

Contributors are recognized in:
- CONTRIBUTORS.md
- GitHub releases
- Project website

Thank you for contributing to WebDrop Bridge! 🎉