flaskpaste/CONTRIBUTING.md

Contributing to FlaskPaste

Development Setup

# 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:

# 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

# 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.