Contributing to Flowrra

We welcome contributions to Flowrra! This guide will help you get started with contributing to the project.

Getting Started 

Prerequisites 

Before contributing, ensure you have:

Python 3.11 or higher
git (for version control)
pip (Python package installer)
A GitHub account

Fork and Clone 

Fork the repository on GitHub: https://github.com/flowrra/flowrra
Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/flowrra.git
cd flowrra

Add the upstream repository:

git remote add upstream https://github.com/flowrra/flowrra.git

Development Setup 

Create Virtual Environment 

# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate     # Windows

Install Dependencies 

Install Flowrra in editable mode with development dependencies:

# Basic installation with dev dependencies
pip install -e ".[dev]"

# With all optional dependencies
pip install -e ".[dev,redis,postgresql,mysql,ui]"

# Or install from requirements files
pip install -r requirements-dev.txt
pip install -e .

Verify Installation 

# Run tests to verify setup
pytest tests/ -v

# Check code quality tools
ruff --version
mypy --version

Making Changes 

1. Create a Feature Branch 

Always create a new branch for your changes:

git checkout -b feature/my-new-feature
# or
git checkout -b fix/issue-123

Branch naming conventions:

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation improvements
refactor/description - Code refactoring
test/description - Test improvements

2. Make Your Changes 

Edit the relevant files. Common areas:

Core code: src/flowrra/
Tests: tests/
Documentation: sphinx-docs/source/
Examples: examples/

3. Write Tests 

All new features and bug fixes must include tests:

# tests/test_my_feature.py
import pytest
from flowrra import Flowrra

class TestMyFeature:
    @pytest.mark.asyncio
    async def test_my_feature(self):
        app = Flowrra.from_urls()

        @app.task()
        async def my_new_task():
            return "feature works!"

        async with app:
            task_id = await app.submit(my_new_task)
            result = await app.wait_for_result(task_id, timeout=2.0)

            assert result.result == "feature works!"

4. Update Documentation 

If your change affects user-facing functionality:

Update relevant .rst files in sphinx-docs/source/
Add code examples if applicable
Update API documentation if needed

5. Run Quality Checks 

Before committing, run all quality checks:

# Run all tests
pytest tests/ -v

# Check code style
ruff check src/ tests/

# Auto-fix style issues
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/

# Type checking
mypy src/flowrra/

# Run everything at once
pytest tests/ -v && ruff check src/ tests/ && mypy src/flowrra/

6. Commit Your Changes 

Write clear, descriptive commit messages:

git add .
git commit -m "Add feature X for Y

- Implement core functionality
- Add comprehensive tests
- Update documentation
- Add examples

Fixes #123"

Commit message guidelines:

First line: concise summary (50 chars or less)
Blank line
Detailed description of changes
Reference related issues

7. Push and Create Pull Request 

git push origin feature/my-new-feature

Then create a Pull Request on GitHub:

Go to your fork on GitHub
Click “New Pull Request”
Select your feature branch
Fill in the PR template
Submit for review

Code Style Guidelines 

We follow strict code quality standards to maintain consistency and reliability.

General Principles 

Type Hints: All functions must have type hints

async def process_task(task_id: str, timeout: float = 5.0) -> TaskResult:
    pass

Docstrings: All public APIs must have docstrings

def create_scheduler(self, backend: str | None = None) -> Scheduler:
    """Create a task scheduler integrated with this Flowrra instance.

    Args:
        backend: Optional database URL for persistent storage.
            Defaults to SQLite if not specified.

    Returns:
        Scheduler instance configured with this app's executors.
    """
    pass

Async/Await: Use async/await for I/O operations

# Good
async def fetch_data(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.json()

Line Length: Maximum 100 characters per line

Imports: Organized by standard library, third-party, local

# Standard library
import asyncio
from typing import Dict, List

# Third-party
import redis.asyncio as redis

# Local
from flowrra.task import Task
from flowrra.exceptions import FlowrraError

Testing Guidelines 

Test Requirements 

Every new feature must have tests
Every bug fix must have a regression test
Aim for >90% code coverage
All tests must pass before merging

Writing Tests 

Use pytest with async support:

import pytest
from flowrra import Flowrra

@pytest.mark.asyncio
async def test_task_execution():
    """Test basic task execution."""
    app = Flowrra.from_urls()

    @app.task()
    async def add(a: int, b: int) -> int:
        return a + b

    async with app:
        task_id = await app.submit(add, 2, 3)
        result = await app.wait_for_result(task_id, timeout=5.0)

        assert result.result == 5
        assert result.status == "success"

Running Tests 

# Run all tests
pytest tests/ -v

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

# Run with coverage
pytest tests/ --cov=flowrra --cov-report=html

# Run only fast tests
pytest tests/ -m "not slow"

# Run tests requiring Redis
pytest tests/test_redis_backend.py -v

Test Organization 

Tests are organized by component:

test_task.py - Task model tests
test_registry.py - Task registry tests
test_executors.py - Executor tests
test_scheduler.py - Scheduler tests
test_backends.py - Backend tests
test_integration.py - End-to-end tests

Pull Request Guidelines 

PR Checklist 

Before submitting a PR, ensure:

[ ] All tests pass
[ ] Code style checks pass (ruff)
[ ] Type checks pass (mypy)
[ ] Documentation is updated
[ ] Changelog is updated (for significant changes)
[ ] Commit messages are clear and descriptive
[ ] PR description explains the changes
[ ] Related issues are referenced

PR Description Template 

## Description
Brief description of what this PR does.

## Motivation
Why is this change needed? What problem does it solve?

## Changes
- Change 1
- Change 2
- Change 3

## Testing
How was this tested?

## Related Issues
Fixes #123
Relates to #456

Review Process 

Automated Checks: CI runs tests and quality checks
Code Review: Maintainers review the code
Feedback: Address any comments or suggestions
Approval: At least one maintainer approval required
Merge: Maintainer merges the PR

Common Contribution Areas 

Bug Fixes 

Search for existing issues
Create an issue if one doesn’t exist
Create a branch: fix/issue-123
Write a failing test that reproduces the bug
Fix the bug
Verify the test now passes
Submit PR

New Features 

Discuss the feature in an issue first
Get feedback from maintainers
Create a branch: feature/my-feature
Implement the feature
Add comprehensive tests
Update documentation
Submit PR

Documentation 

Documentation improvements are always welcome:

Fix typos or unclear explanations
Add examples
Improve API documentation
Add tutorials or guides

# Build documentation locally
cd sphinx-docs
make html
open build/html/index.html  # macOS

Backend Development 

Adding a new backend:

Create src/flowrra/backends/my_backend.py
Inherit from BaseResultBackend
Implement required methods
Add tests in tests/test_my_backend.py
Update factory in backends/__init__.py
Document usage

Scheduler Development 

Working on scheduler features:

Understand the scheduler architecture
Implement changes in src/flowrra/scheduler/
Add backend tests if needed
Test with SQLite, PostgreSQL, and MySQL
Update scheduling documentation

UI Development 

Improving the web UI:

UI code is in src/flowrra/ui/
Templates in src/flowrra/ui/templates/
Test with FastAPI, Flask, and Django
Ensure responsive design
Update UI documentation

Release Process 

For Maintainers 

Version Bump:

# Update version in:
# - pyproject.toml
# - src/flowrra/__init__.py

Update Changelog:

Document all changes in CHANGELOG.md
Run Full Test Suite:
```
pytest tests/ -v --cov=flowrra
```
Build Package:
```
python -m build
```
Upload to PyPI:
```
python -m twine upload dist/*
```
Create Git Tag:
```
git tag v0.1.8
git push --tags
```

Community Guidelines 

Code of Conduct 

Be respectful and inclusive
Welcome newcomers
Provide constructive feedback
Focus on what is best for the community
Show empathy towards other community members

Communication 

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and general discussion
Pull Requests: Code contributions and reviews

Getting Help 

Read the documentation: https://flowrra.readthedocs.io
Check existing issues: https://github.com/flowrra/flowrra/issues
Ask in discussions: https://github.com/flowrra/flowrra/discussions
Review examples: examples/ directory

Recognizing Contributors 

All contributors are recognized in:

GitHub contributors page
Release notes
Project documentation

Thank you for contributing to Flowrra! 🎉

License 

By contributing to Flowrra, you agree that your contributions will be licensed under the Apache License 2.0.