# Contributing to FlaskPaste

## Development Setup

```bash
# Clone repository
git clone <repository>
cd flaskpaste

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install development tools
pip install ruff mypy pytest pytest-cov bandit

# Run development server
python run.py
```

## Code Quality

All code must pass these checks before merge:

```bash
# Lint and format
ruff check app/ tests/ fpaste
ruff format --check app/ tests/ fpaste

# Type checking
mypy app/ tests/ fpaste --ignore-missing-imports

# Security scan
bandit -r app/ -ll -q

# Tests
pytest tests/ -v --tb=short
```

## Testing

```bash
# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_api.py -v

# Run with coverage
pytest tests/ --cov=app --cov-report=term-missing

# Run security tests only
pytest tests/test_security.py tests/test_rate_limiting.py -v
```

## Commit Guidelines

- Use lowercase, imperative mood: `fix: resolve rate limit bypass`
- Prefix with category: `fix:`, `feat:`, `docs:`, `ci:`, `test:`, `refactor:`
- Keep subject under 50 characters
- One logical change per commit

Examples:
```
fix: validate algorithm parameter in PKI methods
feat: add shell completions for bash/zsh/fish
docs: update API documentation for v1.5
ci: enforce mypy type checking
```

## Code Style

- Follow PEP 8 (enforced by ruff)
- Use type hints for all function signatures
- Docstrings for public functions (Google style)
- Maximum line length: 100 characters

## Security

- Never commit secrets or credentials
- Use parameterized queries for all database operations
- Validate all user input
- Follow OWASP guidelines for web security

Report security vulnerabilities privately (see SECURITY.md).

## Pull Requests

1. Create a feature branch from `main`
2. Make changes with atomic commits
3. Ensure all checks pass locally
4. Submit PR with clear description
5. Address review feedback

## Project Structure

```
flaskpaste/
├── app/                    # Application code
│   ├── __init__.py         # App factory
│   ├── api/                # API routes
│   ├── audit.py            # Audit logging
│   ├── config.py           # Configuration
│   ├── database.py         # SQLite operations
│   ├── metrics.py          # Prometheus metrics
│   └── pki.py              # Certificate management
├── tests/                  # Test suite
├── fpaste                  # CLI client
├── run.py                  # Development server
├── wsgi.py                 # Production WSGI entry
└── requirements.txt        # Dependencies
```

## License

By contributing, you agree that your contributions will be licensed under the project's license.