18 Documento di Governance

Documento di Governance

Prevenzione del Debito Tecnico Dipendenziale e Gestione delle Evoluzioni di LangChain

Progetto: FIRE
Versione: 1.0
Data: 2025-11-11
Responsabile: Team di Sviluppo
Stato: Approvato

---

1. Premessa

Durante la stabilizzazione dell’ambiente Python del progetto FIRE è emerso un debito tecnico critico: l’applicazione funzionava solo in un ambiente virtuale “magico”, non documentato e non riproducibile.
La causa principale è stata l’assenza di un file requirements.txt bloccato e l’impatto di una breaking-change dell’ecosistema LangChain (0.1 → 0.2 → 1.0) che ha:

• spostato i moduli interni (langchain.chains → langchain.chains.combine_documents, ecc.)
• introdotto vincoli di versione incrociata tra i sotto-pacchetti (langchain-openai, langchain-core, …)
• reso obsoleto il vecchio helper load_qa_chain in favore di create_stuff_documents_chain / LCEL

Il presente documento definisce le regole, i controlli e i processi per evitare che situazioni analoghe si ripetano.

---

2. Obiettivi

a. Riproducibilità al 100 %: un nuovo dev deve clonare il repo e lanciare un solo comando per ottenere l’ambiente identico.
b. Upgrade controllati: ogni aggiornamento di dipendenza deve essere esplicito, testato, reversibile.
c. No-Sorprese: breaking-change, deprecations, cambi di nome modulo devono essere anticipati e documentati.

---

3. Strumenti e Flussi Obbligatori

Step	Tool	Comando / File	Descrizione
1	pip-tools	requirements.in	Unica fonte verità per le dipendenze di primo livello.
2	pip-tools	pip-compile	Genera requirements.txt bloccato con hash SHA.
3	pip-tools	pip-sync	Sincronizza l’ambiente locale con il lock (rimuove pacchetti orfani).
4	pre-commit	.pre-commit-config.yaml	Hook che blocca il commit se requirements.txt non è allineato a requirements.in.
5	CI	GitHub Actions / GitLab CI	Job che esegue pip-compile --generate-hashes e verifica che il lock sia aggiornato.
6	Renovate / Dependabot	renovate.json	PR automatiche per patch/minor; major bloccate e richiedono review umana.

---

4. Regole di Scrittura del requirements.in

1. Ogni dipendenza diretta deve essere elencata con upper-bound compatibile con la major corrente:

   langchain>=0.2.5,<0.3
   langchain-openai>=0.1.8,<0.2
   

2. Mai lasciare versioni “sciolte” (langchain) senza upper-bound.
3. Commentare il motivo del pinning (es. “compatibile con Python 3.11”).
4. Repository extra (es. PyTorch CUDA) devono essere dichiarati in cima con --extra-index-url.
5. Dipendenze da Git devono essere fissate al commit SHA e documentate:

   # dipendenza custom Google – commit v1.2.3 del 2025-10-01
   timesfm @ git+https://github.com/google-research/timesfm.git@58e01ad82fec7f4e975d708409d51fd5c0131bbd
   

---

5. Processo di Upgrade (minor / major)

Fase	Attività	Output
1. Richiesta	Apertura issue “Upgrade LangChain 0.2 → 0.3”	Checklist template
2. Analisi	pip-compile --upgrade su branch dedicato + lettura changelog upstream	Documento di impatto (breaking, deprecations, nuovi import)
3. Refactor	Aggiornamento codice + import + test suite	PR con diff e test verdi
4. Review	Code-review + QA + test d’integrazione	Approvazione team
5. Merge	Merge su main + tag di versione	Commit atomico + release note
6. Broadcast	Comunicazione a team (Slack / e-mail) con “migration guide” snippet	Archivio confluenza / wiki

---

6. Catalogo delle Breaking-Change Note

Data	Dipendenza	Cambio	Azione Intrapresa
2024-Q2	LangChain 0.1 → 0.2	langchain.chains.* spostati in langchain.chains.combine_documents / retrieval	Refactor import + pinning <0.3
2024-Q4	LangChain 0.2 → 1.0	Rimossi vecchi chain-helper, richiede core>=1.0	Bloccato upper-bound <0.3 fino a nuovo refactor
2025-01	PySide 6.7	Cambio segnali QML	Aggiornato codice + bound <6.8

---

7. Ambiente di Build Isolato (best-practice apprese)

• pip-tools installato in un venv separato (.ptools) con pip 23.3.2 per evitare bug di compatibilità.
• Script di onboarding unico comando:

  make env  # o: just setup

  che esegue:

  python -m venv .venv
  pip install pip-tools==7.5.1
  pip-compile requirements.in
  pip-sync requirements.txt

---

8. Metriche di Salute (dashboard CI)

• Numero di dipendenze outdated (minor / major) → threshold ≤ 5 minor, 0 major.
• Tempo di setup ambiente da zero → target < 3 min.
• Test suite verde dopo ogni pip-compile --upgrade → 100 % pass.

---

9. Ruoli e Responsabilità

Ruolo	Responsabilità
Tech Lead	approva ogni upgrade major; firma il documento di impatto.
DevOps	mantiene CI, pip-tools, pre-commit; aggiorna la dashboard metriche.
Ogni Developer	segue il flusso obbligatorio; non committa mai dipendenze “sciolte”.

---

10. Revisione e Scadenza

• Il presente documento viene riveduto ogni 6 mesi o in occasione di major upgrade dell’ecosistema principale.
• Prossima scadenza: 2025-05-11

---

Con l’adozione di questo documento il team FIRE garantisce che il debito tecnico dipendenziale non si ripeterà e che ogni evoluzione futura (LangChain 0.3, 1.x, PyTorch 3.x, ecc.) sarà gestita in modo controllato, tracciato e reversibile.