285 lines
6.7 KiB
Markdown
285 lines
6.7 KiB
Markdown
# Quick Start Guide
|
|
|
|
## Project Setup (5 minutes)
|
|
|
|
### 1. Open in VS Code
|
|
|
|
```bash
|
|
# Option A: Open the workspace file directly
|
|
code webdrop_bridge.code-workspace
|
|
|
|
# Option B: Open the folder
|
|
code .
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
|
|
# Activate virtual environment
|
|
source venv/bin/activate # macOS/Linux
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# Install development dependencies
|
|
pip install -r requirements-dev.txt
|
|
```
|
|
|
|
### 3. Verify Installation
|
|
|
|
```bash
|
|
# Run project structure tests
|
|
pytest tests/unit/test_project_structure.py -v
|
|
|
|
# Expected output:
|
|
# test_project_structure.py::test_project_structure PASSED
|
|
# test_project_structure.py::test_essential_files PASSED
|
|
# test_project_structure.py::test_python_package_structure PASSED
|
|
```
|
|
|
|
## Project Structure Overview
|
|
|
|
```
|
|
webdrop-bridge/
|
|
│
|
|
├── src/webdrop_bridge/ ← Main application code
|
|
│ ├── core/ ← Business logic (validator, drag interceptor)
|
|
│ ├── ui/ ← UI components (main window, widgets)
|
|
│ └── utils/ ← Utilities (logging, helpers)
|
|
│
|
|
├── tests/ ← Test suite
|
|
│ ├── unit/ ← Unit tests
|
|
│ ├── integration/ ← Integration tests
|
|
│ └── fixtures/ ← Test data
|
|
│
|
|
├── build/ ← Build automation
|
|
│ ├── windows/ ← Windows-specific
|
|
│ ├── macos/ ← macOS-specific
|
|
│ └── scripts/ ← Build scripts
|
|
│
|
|
├── docs/ ← Documentation
|
|
│ └── ARCHITECTURE.md ← Architecture guide
|
|
│
|
|
├── webapp/ ← Embedded web application
|
|
│ └── index.html ← Test drag-drop page
|
|
│
|
|
├── DEVELOPMENT_PLAN.md ← Detailed roadmap
|
|
├── README.md ← User documentation
|
|
├── CONTRIBUTING.md ← Contributing guidelines
|
|
└── Makefile ← Convenience commands
|
|
```
|
|
|
|
## Current Status
|
|
|
|
**Phase 4 is COMPLETE** - All core features and professional features implemented!
|
|
|
|
### What's Already Implemented
|
|
|
|
**Phase 1-3 (Core Features):**
|
|
- ✅ Configuration system with JSON file support & profiles
|
|
- ✅ Path validator with whitelist-based security
|
|
- ✅ Drag interceptor for web-to-file conversion
|
|
- ✅ Main window with toolbar and WebEngine integration
|
|
- ✅ Windows MSIX and macOS DMG build automation
|
|
- ✅ 99+ unit tests with 85%+ coverage
|
|
|
|
**Phase 4.1 (Auto-Update System - Feb 2026):**
|
|
- ✅ Update manager with Forgejo API integration
|
|
- ✅ Update UI dialogs and status bar integration
|
|
- ✅ Automatic background update checking
|
|
- ✅ 76 tests, 79% coverage
|
|
|
|
**Phase 4.2 (Enhanced Logging - Feb 2026):**
|
|
- ✅ Structured JSON logging with rotation
|
|
- ✅ Performance metrics tracking
|
|
- ✅ Log archival with 30-day retention
|
|
- ✅ 20 tests, 91% coverage
|
|
|
|
**Phase 4.3 (Advanced Configuration - Feb 2026):**
|
|
- ✅ Configuration profiles (work, personal, etc.)
|
|
- ✅ Settings dialog with 5 organized tabs
|
|
- ✅ Configuration validation & import/export
|
|
- ✅ 43 tests, 87% coverage
|
|
|
|
### Next Steps (Phase 5)
|
|
|
|
See [DEVELOPMENT_PLAN.md Phase 5](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3) for:
|
|
- Release candidate testing
|
|
- Cross-platform validation
|
|
- Performance optimization
|
|
- Final packaging and deployment
|
|
|
|
## Common Tasks
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
pytest tests -v
|
|
|
|
# With coverage
|
|
pytest --cov=src/webdrop_bridge
|
|
|
|
# Specific test type
|
|
pytest tests/unit/ -v # Unit tests
|
|
pytest tests/integration/ -v # Integration tests
|
|
```
|
|
|
|
### Running Integration Tests
|
|
|
|
```bash
|
|
pytest tests/integration/ -v
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format code
|
|
tox -e format
|
|
|
|
# Check formatting
|
|
tox -e lint
|
|
|
|
# Type checking
|
|
tox -e type
|
|
|
|
# All checks at once
|
|
tox
|
|
```
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Windows MSI
|
|
python build/scripts/build_windows.py
|
|
|
|
# macOS DMG
|
|
bash build/scripts/build_macos.sh
|
|
```
|
|
|
|
### Documentation
|
|
|
|
```bash
|
|
# Build Sphinx docs
|
|
tox -e docs
|
|
|
|
# View docs
|
|
open docs/_build/html/index.html # macOS
|
|
start docs\_build\html\index.html # Windows
|
|
```
|
|
|
|
## Using Makefile (Convenience)
|
|
|
|
```bash
|
|
# List all commands
|
|
make help
|
|
|
|
# Install dependencies
|
|
make install-dev
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Code quality
|
|
make lint
|
|
make format
|
|
make type
|
|
|
|
# Build
|
|
make build-windows
|
|
make build-macos
|
|
|
|
# Clean
|
|
make clean
|
|
```
|
|
|
|
## VS Code Tips
|
|
|
|
### Debugging
|
|
|
|
1. **Set breakpoint**: Click line number
|
|
2. **Start debugging**: F5 (or Run → Run Without Debugging)
|
|
3. **Step over**: F10
|
|
4. **Step into**: F11
|
|
|
|
Configurations available in `.vscode/launch.json`:
|
|
- Python: Current File
|
|
- WebDrop Bridge (main application)
|
|
|
|
### Testing in VS Code
|
|
|
|
1. **Open test file**: `tests/unit/test_project_structure.py`
|
|
2. **Run test**: Click "Run Test" above test function
|
|
3. **Debug test**: Click "Debug Test"
|
|
|
|
### Recommended Extensions
|
|
|
|
- Python (ms-python.python)
|
|
- Pylance (ms-python.vscode-pylance)
|
|
- Black Formatter (ms-python.black-formatter)
|
|
- Ruff (charliermarsh.ruff)
|
|
|
|
## Configuration
|
|
|
|
Create `.env` file from template:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit as needed:
|
|
- `WEBAPP_URL` - Web app location
|
|
- `ALLOWED_ROOTS` - Whitelisted directories
|
|
- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR
|
|
|
|
## Next Steps
|
|
|
|
**Phase 4 is complete!** Here's what you can do:
|
|
|
|
### To Run the Application
|
|
```bash
|
|
# Run the full application (requires config)
|
|
python -m webdrop_bridge.main
|
|
```
|
|
|
|
### To Run Tests
|
|
```bash
|
|
# Run all tests
|
|
pytest tests -v
|
|
|
|
# Run with coverage
|
|
pytest --cov=src/webdrop_bridge tests
|
|
|
|
# Run specific test file
|
|
pytest tests/unit/test_config.py -v
|
|
```
|
|
|
|
### To Explore Phase 4 Features
|
|
1. **Auto-Update System** → See `src/webdrop_bridge/core/updater.py`
|
|
2. **Enhanced Logging** → See `src/webdrop_bridge/utils/logging.py`
|
|
3. **Configuration Profiles** → See `src/webdrop_bridge/core/config_manager.py`
|
|
4. **Settings Dialog** → See `src/webdrop_bridge/ui/settings_dialog.py`
|
|
|
|
### To Prepare for Phase 5
|
|
1. **Read** [DEVELOPMENT_PLAN.md Phase 5](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3)
|
|
2. **Review** [CHANGELOG.md](CHANGELOG.md) for v1.0.0 Phase 4 additions
|
|
3. **Test on multiple platforms** - Windows, macOS
|
|
4. **Report issues** via GitHub/Forgejo issues
|
|
|
|
### To Contribute
|
|
1. **Review** [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
2. **Choose a Phase 5 task** or bug fix
|
|
3. **Follow TDD** - write tests first
|
|
4. **Run quality checks** → `tox`
|
|
|
|
## Getting Help
|
|
|
|
- 📖 **Documentation**: See README.md, DEVELOPMENT_PLAN.md, docs/
|
|
- 🐛 **Issues**: GitHub Issues tracker
|
|
- 💬 **Questions**: GitHub Discussions
|
|
- 🤝 **Contributing**: See CONTRIBUTING.md
|
|
|
|
---
|
|
|
|
**Phase 4 Complete!** → Next: [DEVELOPMENT_PLAN.md Phase 5](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3) Release Candidates
|