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
• Come Contribuire
• Setup Ambiente di Sviluppo
• Workflow di Sviluppo
• Conventional Commits
• Pull Request Process
• Testing
• Changelog

---

Codice di Condotta

Questo progetto aderisce al Codice di Condotta. 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
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
4. Assicurati che i test passino
5. Aggiorna la documentazione
6. Crea una Pull Request

---

Setup Ambiente di Sviluppo

Prerequisiti

• Python 3.10+
• uv per dependency management
• Git

Setup

# 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

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

# 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

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

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

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

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

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

# 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

# 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

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

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

## [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
• Common Changelog
• FastAPI Documentation
• Pytest Documentation

---

Grazie per il tuo contributo! 🎉