sibilla/docs/CONTRIBUTING.md

🤝 Sibilla — Guida alla Contribuzione

Versione: 0.2.0 Ultimo aggiornamento: 18 Luglio 2026

---

Grazie per il tuo interesse a contribuire a Sibilla! 🎉

Codice di Condotta

Sii rispettoso, costruttivo e inclusivo. Tratta gli altri come vorresti essere trattato.

---

Come Contribuire

1. Segnala un Bug

Apri una issue su GitHub con:

• Titolo descrittivo (es. "Errore 502 quando Degoog è lento")
• Passi per riprodurre il bug
• Comportamento atteso vs comportamento osservato
• Log di errore (se disponibili)
• Ambiente: versione Python, OS, versione Sibilla

2. Proponi una Feature

Apri una issue con il tag enhancement descrivendo:

• Problema che risolve
• Soluzione proposta
• Alternative considerate
• Impatto sul codice esistente

3. Invia una Pull Request

Setup sviluppo

# 1. Forka il repository
# 2. Clona il tuo fork
git clone https://github.com/tuo-user/sibilla.git
cd sibilla

# 3. Aggiungi l'upstream
git remote add upstream https://github.com/original/sibilla.git

# 4. Crea ambiente virtuale
python3 -m venv .venv
source .venv/bin/activate

# 5. Installa dipendenze di sviluppo
pip install -e ".[dev]"

# 6. Configura .env
cp .env.example .env
nano .env  # Inserisci GOOGLE_API_KEY

Flusso di lavoro

# 1. Sincronizza con upstream
git fetch upstream
git checkout master
git merge upstream/master

# 2. Crea un branch
git checkout -b feature/nome-feature
# oppure
git checkout -b fix/nome-bug

# 3. Sviluppa
# ... scrivi codice ...

# 4. Testa
pytest tests/ -v

# 5. Linta
ruff check src tests

# 6. Committa con messaggi chiari
git add .
git commit -m "feat: aggiungi caching risposte con Redis"

# 7. Pusha
git push origin feature/nome-feature

# 8. Apri Pull Request su GitHub

---

Convenzioni del Codice

Stile

• Python 3.10+ con type hints
• Ruff per linting e formattazione (ruff check src tests)
• Line length: 100 caratteri
• Docstring: stile Google ("""Descrizione breve. con Args:, Returns:, Raises:)

Commit Messages

Usiamo Conventional Commits:

feat: aggiungi caching risposte con Redis
fix: correggi race condition in PageFetcher
docs: aggiorna README con esempi API v1
refactor: estrai pipeline condivisa in helper
test: aggiungi test per strip_markdown
chore: aggiorna dipendenze

Struttura dei Branch

Prefisso	Uso
feature/	Nuove funzionalità
fix/	Bug fix
docs/	Documentazione
refactor/	Refactoring
test/	Test
chore/	Manutenzione

---

Test

Esecuzione

# Tutti i test
pytest tests/ -v

# Test specifico
pytest tests/test_app.py -v

# Con coverage
pip install pytest-cov
pytest tests/ --cov=src/sibilla --cov-report=html

Scrivere Test

• Nuove feature = nuovi test. Ogni endpoint, funzione pubblica e classe deve essere testata.
• Naming: test_<funzione>_<scenario>() (es. test_strip_markdown_with_images)
• Fixtures: usa create_app(testing=True) per testare senza .env

Esempio:

def test_api_v1_query_returns_speakable_text(client):
    """Verifica che /api/v1/query includa speakable_text."""
    # Dato che Gemini non è configurato, verifica la risposta di errore
    resp = client.get("/api/v1/query?q=test")
    data = resp.get_json()
    assert "speakable_text" in data

---

Pipeline di Ricerca

Per aggiungere un nuovo passaggio alla pipeline:

1. Identifica il punto di inserimento in _run_search_pipeline() in app.py
2. Implementa la logica in una funzione o classe separata
3. Aggiungi test per il nuovo comportamento
4. Documenta in docs/ARCHITECTURE.md

Aggiungere un Search Engine

1. Crea una classe in search.py che implementi search(query, num_results) → SearchResponse
2. Aggiungi il client in _run_search_pipeline() nella catena di fallback
3. Aggiungi test in tests/test_search.py

class MySearchClient:
    def search(self, query: str, num_results: int = 8) -> SearchResponse:
        # ... implementazione ...
        return SearchResponse(query=query, results=results, engine="myengine")

Aggiungere un Endpoint API

1. Aggiungi una route in app.py
2. Riutilizza _run_search_pipeline() per la logica condivisa
3. Aggiungi test in tests/test_app.py

@app.route("/api/v2/custom", methods=["POST"])
def api_v2_custom():
    # ... usa _run_search_pipeline() ...

---

Documentazione

La documentazione vive in docs/. Quando modifichi una funzionalità, aggiorna:

• docs/API.md — se modifichi endpoint o formati di risposta
• docs/ARCHITECTURE.md — se modifichi l'architettura
• docs/FLOW.md — se modifichi la pipeline
• docs/WIKI.md — per FAQ e roadmap

---

Domande?

Apri una issue su GitHub o contatta i maintainer.

Grazie per contribuire a Sibilla! 🔮