documente/CONTRIBUTING.md

# Contributing to NotebookLM Agent API

Grazie per il tuo interesse nel contribuire al progetto! Questo documento fornisce le linee guida per contribuire efficacemente.

## Indice

- [Codice di Condotta](#codice-di-condotta)
- [Come Contribuire](#come-contribuire)
- [Setup Ambiente di Sviluppo](#setup-ambiente-di-sviluppo)
- [Workflow di Sviluppo](#workflow-di-sviluppo)
- [Conventional Commits](#conventional-commits)
- [Pull Request Process](#pull-request-process)
- [Testing](#testing)
- [Changelog](#changelog)

---

## Codice di Condotta

Questo progetto aderisce al [Codice di Condotta](./CODE_OF_CONDUCT.md). Partecipando, ti impegni a mantenere un ambiente rispettoso e collaborativo.

---

## Come Contribuire

### Segnalare Bug

1. Verifica che il bug non sia già stato segnalato nelle [Issues](../../issues)
2. Crea una nuova issue con:
   - Titolo descrittivo
   - Descrizione chiara del problema
   - Passi per riprodurre
   - Comportamento atteso vs attuale
   - Ambiente (OS, Python version, etc.)
   - Log o screenshot rilevanti

### Suggerire Feature

1. Crea una issue con label `enhancement`
2. Descrivi chiaramente la feature e il valore aggiunto
3. Discuti l'implementazione con i maintainer

### Contribuire al Codice

1. Fork del repository
2. Crea un branch per la tua feature/fix
3. Segui le [Conventional Commits](#conventional-commits)
4. Assicurati che i test passino
5. Aggiorna la documentazione
6. Crea una Pull Request

---

## Setup Ambiente di Sviluppo

### Prerequisiti

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) per dependency management
- Git

### Setup

```bash
# Clona il repository
git clone https://github.com/example/notebooklm-agent.git
cd notebooklm-agent

# Crea virtual environment
uv venv --python 3.10
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

# Installa dipendenze
uv sync --extra dev --extra browser

# Installa pre-commit hooks
uv run pre-commit install

# Verifica setup
uv run pytest --version
uv run ruff --version
```

---

## Workflow di Sviluppo

### 1. Creare un Branch

```bash
# Aggiorna main
git checkout main
git pull origin main

# Crea branch
git checkout -b feat/nome-feature        # Per feature
git checkout -b fix/nome-bug             # Per bugfix
git checkout -b docs/nome-documentazione # Per docs
```

### 2. Sviluppare con TDD

Segui il ciclo Red-Green-Refactor:

```bash
# 1. Scrivi test (fallirà)
# Crea tests/unit/test_nuova_feature.py

# 2. Esegui test (deve fallire)
uv run pytest tests/unit/test_nuova_feature.py -v

# 3. Implementa codice minimo
# Modifica src/notebooklm_agent/...

# 4. Esegui test (deve passare)
uv run pytest tests/unit/test_nuova_feature.py -v

# 5. Refactor mantenendo test verdi
# Migliora codice

# 6. Verifica tutti i test
uv run pytest
```

### 3. Qualità del Codice

```bash
# Linting
uv run ruff check src/ tests/
uv run ruff check --fix src/ tests/

# Formattazione
uv run ruff format src/ tests/

# Type checking
uv run mypy src/notebooklm_agent

# Pre-commit (esegue tutti i check)
uv run pre-commit run --all-files
```

---

## Conventional Commits

Tutti i commit devono seguire la specifica [Conventional Commits](https://www.conventionalcommits.org/).

### Format

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

### Types

| Type | Descrizione |
|------|-------------|
| `feat` | Nuova feature |
| `fix` | Bug fix |
| `docs` | Cambiamenti alla documentazione |
| `style` | Cambiamenti di stile (formattazione, punto e virgola, etc.) |
| `refactor` | Refactoring codice |
| `perf` | Miglioramenti performance |
| `test` | Aggiunta o correzione test |
| `chore` | Task di build, dipendenze, etc. |
| `ci` | Cambiamenti CI/CD |

### Scopes

| Scope | Descrizione |
|-------|-------------|
| `api` | REST API endpoints |
| `webhook` | Webhook system |
| `skill` | AI skill interface |
| `notebook` | Notebook operations |
| `source` | Source management |
| `artifact` | Artifact generation |
| `auth` | Authentication |
| `core` | Core utilities |
| `deps` | Dependencies |
| `config` | Configuration |

### Esempi

```bash
# Feature
git commit -m "feat(api): add webhook registration endpoint"
git commit -m "feat(notebook): implement bulk create operation"

# Fix
git commit -m "fix(webhook): retry logic exponential backoff"
git commit -m "fix(auth): handle expired tokens correctly"

# Docs
git commit -m "docs(api): update OpenAPI schema"
git commit -m "docs(readme): add installation instructions"

# Test
git commit -m "test(source): add unit tests for URL validation"
git commit -m "test(webhook): add integration tests for retry logic"

# Refactor
git commit -m "refactor(notebook): extract validation logic"
git commit -m "refactor(core): improve error handling"

# Chore
git commit -m "chore(deps): upgrade notebooklm-py to 0.3.4"
git commit -m "chore(ci): add GitHub Actions workflow"
```

### Commit con Body

Per commit complessi, usa il body:

```bash
git commit -m "feat(api): add batch source import endpoint

- Support for multiple URLs in single request
- Async processing with webhook notification
- Rate limiting per user

Fixes #123"
```

### Breaking Changes

```bash
git commit -m "feat(api)!: change response format for notebooks endpoint

BREAKING CHANGE: response now wrapped in 'data' key
Migration guide: docs/migrations/v1-to-v2.md"
```

---

## Pull Request Process

### 1. Prima di Creare PR

```bash
# Aggiorna dal main
git checkout main
git pull origin main
git checkout tuo-branch
git rebase main

# Esegui test completi
uv run pytest

# Verifica qualità
uv run pre-commit run --all-files

# Aggiorna CHANGELOG.md se necessario
```

### 2. Creare PR

1. Vai su GitHub e crea PR verso `main`
2. Usa il template PR fornito
3. Assicurati che:
   - Titolo segue conventional commits
   - Descrizione spiega cosa e perché
   - Test inclusi per nuove feature
   - Documentazione aggiornata
   - CHANGELOG.md aggiornato

### 3. Review Process

1. Richiedi review da almeno 1 maintainer
2. Rispondi ai commenti
3. Fai push delle correzioni
4. Attendi approvazione

### 4. Merge

- Usa "Squash and Merge"
- Il titolo del merge commit deve seguire conventional commits
- Elimina il branch dopo il merge

---

## Testing

### Eseguire Test

```bash
# Tutti i test
uv run pytest

# Con coverage
uv run pytest --cov=src/notebooklm_agent --cov-report=term-missing

# Solo unit test
uv run pytest tests/unit/ -m unit

# Solo integration test
uv run pytest tests/integration/ -m integration

# Solo E2E (richiede auth)
uv run pytest tests/e2e/ -m e2e

# Test specifico
uv run pytest tests/unit/test_notebook_service.py::test_create_notebook -v

# Test falliti solo
uv run pytest --lf

# Parallel (con pytest-xdist)
uv run pytest -n auto
```

### Scrivere Test

```python
# tests/unit/test_example.py
import pytest
from notebooklm_agent.services.notebook_service import NotebookService


@pytest.mark.unit
class TestNotebookService:
    """Test suite for NotebookService."""

    async def test_create_notebook_valid_title_returns_created(self):
        """Should create notebook with valid title."""
        # Arrange
        service = NotebookService()
        title = "Test Notebook"

        # Act
        result = await service.create_notebook(title)

        # Assert
        assert result.title == title
        assert result.id is not None

    async def test_create_notebook_empty_title_raises_validation_error(self):
        """Should raise error for empty title."""
        # Arrange
        service = NotebookService()

        # Act & Assert
        with pytest.raises(ValidationError):
            await service.create_notebook("")
```

---

## Changelog

Il progetto segue le specifiche [Common Changelog](https://common-changelog.org/).

### Aggiornare CHANGELOG.md

Quando crei una PR che cambia il comportamento visibile:

1. Aggiungi entry sotto la sezione "Unreleased"
2. Usa i gruppi:
   - `### Added` - Nuove feature
   - `### Changed` - Cambiamenti a feature esistenti
   - `### Deprecated` - Feature deprecate
   - `### Removed` - Feature rimosse
   - `### Fixed` - Bug fix
   - `### Security` - Fix di sicurezza

### Esempio

```markdown
## [Unreleased]

### Added

- Add webhook retry mechanism with exponential backoff. ([`abc123`])
- Support for batch source import via API. ([`def456`])

### Fixed

- Fix race condition in artifact status polling. ([`ghi789`])

## [0.1.0] - 2026-04-05

### Added

- Initial release with core API functionality.
```

---

## Risorse

- [Conventional Commits](https://www.conventionalcommits.org/)
- [Common Changelog](https://common-changelog.org/)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Pytest Documentation](https://docs.pytest.org/)

---

Grazie per il tuo contributo! 🎉