Adozione di pip-tools per la Gestione Deterministica delle Dipendenze

ADR 0006: Adozione di pip-tools per la Gestione Deterministica delle Dipendenze

Contesto

Durante il tentativo di rollback dalla v0.12.0 alla v11.28, il team ha incontrato un blocco totale dello sviluppo. Si è scoperto che l’ambiente di sviluppo della v11.28, sebbene funzionante, non era riproducibile.

I tentativi di clonare l’ambiente utilizzando lo standard pip freeze > requirements.txt e poi pip install -r requirements.txt sono falliti sistematicamente per due ragioni principali:

1. Dipendenze non Tracciate: Pacchetti critici (es. timesfm) non erano gestiti da pip e quindi assenti dal requirements.txt.
2. Conflitti Latenti: Il requirements.txt conteneva una “fotografia” di un ambiente con versioni di pacchetti teoricamente incompatibili (es. urllib3), che pip non poteva risolvere partendo da un’installazione pulita.

Questa situazione ha causato giorni di ritardo e ha evidenziato una vulnerabilità critica nel nostro processo di sviluppo: la mancanza di una gestione delle dipendenze affidabile e deterministica.

Decisione

Si decide di abbandonare ufficialmente pip freeze come strumento per la gestione degli ambienti.

Viene adottato come nuovo standard obbligatorio il workflow basato su pip-tools, che si articola sui seguenti artefatti:

1. requirements.in: Un file gestito manualmente che elenca solo le dipendenze di alto livello del progetto. Diventa la nostra “fonte di verità logica”.
2. pip-compile: Lo strumento utilizzato per leggere requirements.in e generare un file di lock.
3. requirements.lock.txt: Un file generato automaticamente che contiene l’intero albero delle dipendenze, con ogni pacchetto bloccato a una versione esatta e verificato tramite hash. Diventa la nostra “fonte di verità fisica” per la riproducibilità.
4. pip-sync: Lo strumento utilizzato per forzare un ambiente virtuale a rispecchiare esattamente il contenuto del requirements.lock.txt.

Conseguenze

Positive

• Riproducibilità Garantita: Ogni sviluppatore, in qualsiasi momento, può ricreare un ambiente di sviluppo identico e funzionante eseguendo un unico comando.
• Stabilità: Si eliminano i bug “fantasma” causati da discrepanze tra gli ambienti degli sviluppatori.
• Chiarezza: Le dipendenze dirette del progetto sono ora esplicite e chiaramente separate da quelle transitive.
• Sicurezza: L’uso degli hash nel lockfile protegge da installazioni di pacchetti potenzialmente compromessi (supply chain attacks).

Negative

• Aumento della Complessità del Workflow: Il processo per aggiungere o aggiornare una dipendenza non è più un singolo pip install, ma richiede un processo a più passaggi (modifica di .in, ricompilazione del .lock, sincronizzazione). Questo richiede una formazione iniziale per il team.
• Introduzione di un Nuovo Strumento: pip-tools diventa una dipendenza del nostro processo di sviluppo.

Alternative Considerate

• Continuare con pip freeze: Scartato perché si è dimostrato inaffidabile e la causa diretta del nostro blocco.
• Adottare Strumenti più Complessi (es. Poetry, PDM): Scartato per ora. Sebbene potenti, introducono un livello di complessità e un cambio di paradigma (gestione del progetto tramite pyproject.toml) che non è necessario in questa fase. pip-tools offre il miglior compromesso tra potenza e semplicità, integrandosi con il nostro uso esistente di pip e venv.
• Copia “Bruta” degli Ambienti Virtuali: Scartato perché non è una soluzione scalabile, è dipendente dalla piattaforma e non risolve il problema della riproducibilità su macchine diverse.