feat(api): implement notebook management CRUD endpoints
Implement Sprint 1: Notebook Management CRUD
- Add NotebookService with full CRUD operations
- Add POST /api/v1/notebooks (create notebook)
- Add GET /api/v1/notebooks (list with pagination)
- Add GET /api/v1/notebooks/{id} (get by ID)
- Add PATCH /api/v1/notebooks/{id} (partial update)
- Add DELETE /api/v1/notebooks/{id} (delete)
- Add Pydantic models for requests/responses
- Add custom exceptions (ValidationError, NotFoundError, NotebookLMError)
- Add comprehensive unit tests (31 tests, 97% coverage)
- Add API integration tests (26 tests)
- Fix router prefix duplication
- Fix JSON serialization in error responses
BREAKING CHANGE: None
This commit is contained in:
Luca Sacchi Ricciardi
403
CONTRIBUTING.md
Normal file
403
CONTRIBUTING.md
Normal file
@@ -0,0 +1,403 @@
|
||||
# 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! 🎉
|
||||
Reference in New Issue
Block a user