forked from claw/flaskpaste
120 lines
2.8 KiB
Markdown
120 lines
2.8 KiB
Markdown
# 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.
|