Add initial project structure and documentation

- Created architecture documentation outlining high-level design, module organization, data flow, security model, performance considerations, testing strategy, and deployment architecture. - Added pyproject.toml for project metadata and dependencies management. - Introduced requirements files for development and production dependencies. - Set up testing configuration with pytest and tox. - Established basic directory structure for source code and tests, including __init__.py files. - Implemented a sample web application (index.html) for drag-and-drop functionality. - Configured VS Code workspace settings for Python development.
2026-01-28 10:48:36 +01:00 · 2026-01-28 10:48:36 +01:00 · 61aa33633c
commit 61aa33633c
34 changed files with 5342 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,363 @@
+# 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
+
+## 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! 🎉