Documento di Onboarding V2: Stabilizzazione e Modernizzazione del Progetto “FIRE”
A: Nuovo Collaboratore Da: Team di Sviluppo Oggetto: Piano operativo per il recupero e l’aggiornamento della gestione dipendenze del progetto FIRE.
Benvenuto/a nel team!
Questo documento ti guiderà attraverso il processo strategico che stiamo implementando per risolvere un debito tecnico critico nel progetto FIRE: la gestione delle dipendenze.
Obiettivo Strategico
Il progetto soffre di “dependency hell”: funziona grazie a un ambiente virtuale “magico” che non è documentato né riproducibile. Il nostro obiettivo è duplice:
- Stabilizzazione Immediata: Sbloccare il team generando un file
requirements.txtaffidabile che renda l’ambiente replicabile al 100%. - Modernizzazione a Lungo Termine: Migrare a un sistema di gestione delle dipendenze moderno (Poetry) per garantire la manutenibilità futura del progetto e prevenire il ripetersi di questo problema.
Seguiremo una strategia in due fasi: prima risolviamo l’emergenza, poi costruiamo le fondamenta per il futuro.
Fase 1: Stabilizzazione Immediata con un Ambiente di Build Isolato
Obiettivo: Generare un file requirements.txt bloccato e verificato senza inquinare o modificare l’ambiente di sviluppo del progetto.
Metodologia: Useremo uno strumento (pip-tools) installato in un ambiente virtuale separato e “congelato” (.ptools), che agirà come una “fabbrica” per il nostro requirements.txt. Questo ci permette di aggirare un’incompatibilità nota tra le versioni recenti di pip e pip-tools.
Prerequisiti:
- Hai una cartella di lavoro pulita:
D:\01_DevOps\fire\fireDev_rebuild. - All’interno di questa cartella, hai già creato e attivato un ambiente virtuale per il progetto:
.venv. - Hai già creato il file
requirements.inbasato sull’analisi architetturale.
Guida Passo-Passo (Fase 1)
Tutti i comandi seguenti devono essere eseguiti dal terminale, nella directory principale del progetto: D:\01_DevOps\fire\fireDev_rebuild.
1. Creazione dell’Ambiente di Build Isolato (.ptools)
Questo passo va eseguito una sola volta. Creeremo un mini-ambiente che contiene solo la versione corretta di pip-tools e pip con cui è compatibile.
# Crea un nuovo ambiente virtuale chiamato .ptools
python -m venv .ptools
# Usa il pip di .ptools per installare una versione compatibile di pip e pip-tools
# NOTA: Usiamo il percorso esplicito per essere sicuri di modificare .ptools, non il .venv del progetto.
.\.ptools\Scripts\pip.exe install "pip==23.3.2" pip-tools==7.5.1Risultato Atteso: Avrai una nuova cartella .ptools contenente il nostro strumento di build specializzato e “congelato” nel tempo.
2. Generazione del File requirements.txt
Ora usiamo il nostro strumento isolato per compilare il requirements.in e produrre il file di lock finale.
# Invoca il pip-compile che si trova dentro .ptools per generare il file
.\.ptools\Scripts\pip-compile.exe requirements.in -o requirements.txtRisultato Atteso: Un nuovo file requirements.txt apparirà nella tua cartella. Sarà un file lungo e dettagliato, contenente ogni singola dipendenza con la sua versione esatta.
3. Installazione e Verifica dell’Ambiente di Progetto
Adesso popoliamo l’ambiente virtuale del nostro progetto (.venv) usando il file appena creato.
# Assicurati che il venv del progetto sia attivo
# Il prompt dovrebbe iniziare con (.venv)
.\.venv\Scripts\Activate.ps1
# Installa tutte le dipendenze dal file di lock
pip install -r requirements.txtNota: Questo comando potrebbe richiedere diversi minuti.
4. Test Funzionale Una volta terminata l’installazione, lancia l’applicazione e verifica che le funzionalità principali si comportino come previsto.
python main.py5. Commit degli Artefatti Se i test hanno successo, l’emergenza è finita. L’ambiente è ora riproducibile. Fai un commit dei file che definiscono questo stato:
git add requirements.in requirements.txt
git commit -m "feat: Stabilize project dependencies with a locked requirements file"Obiettivo della Fase 1 Raggiunto: Il progetto è ora sbloccato. Chiunque nel team può creare un ambiente di sviluppo identico eseguendo pip install -r requirements.txt.
Fase 2: Migrazione Strategica a Poetry
Obiettivo: Adottare Poetry come gestore di dipendenze, ambienti e build per garantire la salute del progetto a lungo termine.
Metodologia: Eseguiremo una migrazione graduale e non distruttiva. Introdurremo Poetry facendolo convivere con il sistema requirements.txt esistente, per poi dismettere quest’ultimo una volta che il team si sarà adattato al nuovo workflow.
Guida Passo-Passo (Fase 2)
Continua a lavorare nella stessa directory D:\01_DevOps\fire\fireDev_rebuild.
1. Installazione di Poetry (Metodo Ufficiale) Poetry è uno strumento di sistema e non deve essere installato all’interno dell’ambiente virtuale del progetto. Lo installeremo a livello utente, come raccomandato dalla documentazione ufficiale.
# Esegui questo comando in PowerShell per installare Poetry per l'utente corrente
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -Nota: Potrebbe essere necessario riavviare il terminale dopo l’installazione per rendere disponibile il comando poetry.
2. Inizializzazione del Progetto Poetry
Ora che Poetry è disponibile, lo usiamo per inizializzare il nostro progetto. Questo creerà il file pyproject.toml.
# Questo comando ti farà alcune domande; puoi accettare i valori di default.
poetry initRisultato Atteso: Un nuovo file pyproject.toml nella cartella del progetto.
3. Importazione delle Dipendenze in Poetry (Metodo Robusto)
Invece di un lungo comando poetry add, useremo un approccio più robusto per importare tutte le dipendenze dal nostro requirements.txt appena generato.
Opzione A (Per PowerShell e Git Bash/WSL):
# Questo comando legge il file, rimuove i commenti e le righe vuote, e passa tutto a poetry.
# È preferibile eseguirlo in un terminale Git Bash o WSL se disponibile.
poetry add $(cat requirements.txt | sed 's/#.*//' | grep -v '^$')Opzione B (Alternativa più semplice se il comando sopra fallisce): Usa un piccolo tool per la conversione.
pip install requirements-to-poetry
requirements-to-poetryQuesto leggerà requirements.txt e aggiornerà pyproject.toml di conseguenza. Successivamente, esegui:
poetry lock --no-update4. Blocco Finale e Commit
A prescindere dal metodo di importazione, ora abbiamo tutte le informazioni in pyproject.toml. Generiamo il file di lock nativo di Poetry.
poetry lockRisultato Atteso: Un nuovo file poetry.lock è stato creato. Questo file è l’equivalente, ma più potente e cross-platform, del requirements.txt.
Ora, fai un commit dei nuovi file di Poetry:
git add pyproject.toml poetry.lock
git commit -m "feat: Introduce Poetry for dependency management"Obiettivo della Fase 2 Raggiunto: Il progetto ora supporta due sistemi di gestione delle dipendenze. I membri del team possono iniziare a usare Poetry gradualmente, mentre il requirements.txt garantisce la compatibilità per chi non ha ancora migrato.
Nuovo Workflow Operativo (Post-Migrazione)
Una volta completata la migrazione, il workflow quotidiano diventerà molto più semplice.
| Azione | Vecchio Metodo (da dismettere) | Nuovo Metodo con Poetry |
|---|---|---|
| Setup del Progetto | python -m venv .venvpip install -r requirements.txt | poetry install (crea venv e installa tutto) |
| Aggiungere una Libreria | Aggiungere nuova-libreria a requirements.in.\.ptools\Scripts\pip-compile.exe ...pip install -r requirements.txt | poetry add nuova-libreria |
| Aggiornare Librerie | .\.ptools\Scripts\pip-compile.exe --upgrade ...pip install -r requirements.txt | poetry update |
| Eseguire uno Script | .\.venv\Scripts\Activate.ps1python mio_script.py | poetry run python mio_script.py |
Il passo finale, da eseguire in futuro, sarà eliminare i file requirements.in, requirements.txt e la cartella .ptools una volta che tutto il team avrà adottato Poetry.
Benvenuto/a a bordo e buon lavoro