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

```bash
# 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

```bash
# 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](https://www.conventionalcommits.org/):

```
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

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

```python
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`

```python
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`

```python
@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! 🔮