Git workflow, code review e collaborazione tecnica

Quando più persone modificano modelli che alimentano dashboard critici, il workflow Git diventa parte della qualità del dato. Git workflow, code review e collaborazione tecnica porta pull request, review, naming e ownership nel lavoro quotidiano dell’analytics engineer.

Una scena da cui partire

Leggi la lezione come pratica di collaborazione tecnica. Una review dbt non deve solo cercare errori: deve chiarire impatto, leggibilità, test, lineage e compatibilità con contratti esistenti.

• Contesto: Quale decisione rende utile il concetto?
• Metodo: Quale conflitto tra team o metriche devi anticipare?
• Applicazione: Quale frase useresti per spiegarlo in riunione?

Il Git workflow per progetti dbt

dbt è codice. Il branching model che funziona per il software funziona anche per i dati. Il pattern consigliato è trunk-based con feature branch:

main ──────────────────────────────────────────────► (produzione)
  │
  ├── feature/new-mrr-model ──► PR ──► review ──► merge
  │
  ├── fix/campaign-cost-bug ──► PR ──► review ──► merge
  │
  └── staging ──► (deploy automatico su env di test)

Regole del workflow:

1. Mai commitare direttamente su main. Ogni modifica è un branch + PR.
2. Ogni PR esegue dbt build sul proprio schema separato. Il CI/CD crea uno schema pr_123 e builda solo i modelli modificati.
3. La PR si può mergiare solo se il build è verde E almeno un reviewer ha approvato.
4. Il merge su main triggera il deploy in produzione (o su staging, a seconda dell’ambiente).

Code review per modelli dati: cosa guardare

La code review di un modello dbt è diversa dalla code review di codice applicativo. Ecco cosa controllare, in ordine di importanza:

1. I test ci sono e sono sufficienti? La prima domanda è sempre: “Come faccio a sapere se questo modello produce dati sbagliati?” Se la risposta è “non lo so” o “lo vedrei a occhio”, la PR va bloccata finché non ci sono test. Almeno not_null sulla primary key.

2. La logica di business è nel layer giusto? Se un modello mart contiene CASE WHEN complessi con regole di business, quella logica dovrebbe essere in intermediate. Se un modello staging contiene JOIN, è nel layer sbagliato.

3. Il naming è chiaro? int_dly_cust_rev non è chiaro. int_daily_customer_revenue lo è. Il nome del file e il nome del modello devono coincidere.

4. C’è documentazione YAML? Ogni modello deve avere un file .yml associato con description, test su colonne critiche, e source/ref appropriati.

5. La query è performante? Uno SELECT * senza WHERE su una tabella da 2 miliardi di righe è un allarme rosso. Chiedere il piano di esecuzione (EXPLAIN) per modelli su tabelle grandi.

Template di checklist per PR reviewer:

[ ] Test: not_null + unique sulla primary key
[ ] Layer: la logica di business è nel layer corretto?
[ ] Naming: file, modello, colonne seguono le convenzioni
[ ] Docs: YAML con description per ogni colonna critica
[ ] Perf: il modello scala sui volumi di produzione?
[ ] Dependencies: il DAG è aciclico? (dbt lo controlla automaticamente)

Caso reale: la collaborazione in dbt nel team dati di GitLab

GitLab ha documentato il proprio workflow di collaborazione sui dati nel handbook pubblico. Il loro processo per una modifica a un modello dbt:

1. L’analyst crea un branch feature/update-churn-definition con le modifiche SQL + YAML.
2. Crea una MR (Merge Request) su GitLab. Il CI esegue automaticamente:
   • dbt build --select state:modified+ --target ci su uno schema isolato
   • Validazione YAML e linting SQL
3. Un analytics engineer senior fa la review usando la checklist sopra.
4. Se approvata, la MR viene mergiata su main. Un pipeline automatico esegue:
   • dbt run --target production
   • dbt test --target production
5. Se il build produzione fallisce, un alert su Slack notifica il team e la MR può essere revertita automaticamente.

GitLab ha riportato che questo processo ha ridotto gli incidenti di dati errati dell’89% e ha portato il numero di contributori ai modelli dati da 3 a 14 (i product analyst hanno iniziato a contribuire perché il processo era chiaro e sicuro).

Gestione dei conflitti su modelli dbt

I conflitti su modelli dbt sono più pericolosi dei conflitti su codice perché il merge tool di Git non capisce SQL. Due strategie per minimizzarli:

1. Modelli piccoli e con responsabilità singola. Un modello che calcola 20 metriche diverse per 5 team sarà toccato da più persone e genererà più conflitti. Separare in modelli più piccoli riduce la superficie di conflitto.

2. Schema separation per sviluppatore. In locale, ogni sviluppatore usa uno schema dedicato: dbt_anna, dbt_marco, ecc. Il profiles.yml usa variabili d’ambiente:

my_project:
  target: dev
  outputs:
    dev:
      schema: "dbt_{{ env_var('USER', 'default') }}"

Questo impedisce che due sviluppatori si pestino i piedi sullo stesso schema e rende facile testare in isolamento.

---

Riferimenti:

• GitLab. (2024). “Data Team Handbook: Git Workflow.” GitLab Handbook.
• dbt Labs. (2023). “Best Practices for dbt Project Collaboration.” dbt Developer Blog.
• Forsgren, N., Humble, J., & Kim, G. (2018). Accelerate: The Science of Lean Software and DevOps. IT Revolution Press.

Controllo di qualità

Prima di usare git workflow, code review e collaborazione tecnica in una decisione, controlla sempre completezza, duplicati, timezone, definizioni cambiate e segmenti esclusi. Molte analisi apparentemente sofisticate falliscono perché il dato di partenza misura un comportamento diverso da quello che il team crede di osservare.

Interpretazione per segmenti

La media aggregata è solo il punto di partenza. Segmenta per canale, coorte, piano, paese, device e maturità dell’utente. Se due segmenti si muovono in direzioni opposte, la media non rappresenta nessuno dei due e può portare a una decisione sbagliata.

Decisione operativa

Ogni analisi deve terminare con una scelta possibile: continuare, fermare, iterare, investire, rimuovere o approfondire. Se git workflow, code review e collaborazione tecnica non cambia una decisione, probabilmente manca ancora il collegamento tra metrica e azione.

Problema reale

Nel dominio di analytics engineering, Git workflow, code review e collaborazione tecnica serve a risolvere questo problema: trasformare dati grezzi in modelli testati, documentati e riusabili dal business. La lezione non va trattata come teoria isolata, ma come un modo per migliorare una scelta concreta con dati, assunzioni esplicite e controlli minimi.

Obiettivo operativo: Comprendere il problema analitico e il contesto decisionale; Applicare esempi, metriche e controlli a casi reali. Se alla fine non sai indicare quale decisione cambia, quale dato osservi e quale errore vuoi evitare, la lezione non è ancora diventata competenza applicata.

Modello concettuale

Fase	Cosa chiarire	Output
Domanda	Quale scelta reale deve migliorare?	Decisione da prendere
Misura	Quale segnale osservabile rappresenta il problema?	Metrica o dato sorgente
Controllo	Quale baseline rende il risultato interpretabile?	Confronto credibile
Azione	Che cosa cambia dopo l’analisi?	Prossimo passo operativo

Il modello concettuale è intenzionalmente semplice: decisione, dato, controllo, azione. Ogni approfondimento tecnico deve rafforzare almeno uno di questi quattro punti.

Formalizzazione rigorosa

Per rendere Git workflow, code review e collaborazione tecnica analizzabile, definisci prima l’unità di lavoro: source, model, test, mart, metrica o esposizione. Poi collega questa unità a una metrica osservabile: freshness, lineage, test coverage, costo modello e fiducia stakeholder. Infine dichiara la decisione attesa: modello dbt, semantic layer, contratto, test o pipeline di release.

Elemento	Specifica richiesta
Unità di analisi	source, model, test, mart, metrica o esposizione
Segnale principale	freshness, lineage, test coverage, costo modello e fiducia stakeholder
Baseline	Periodo precedente, gruppo comparabile, benchmark o scenario controfattuale
Decisione	modello dbt, semantic layer, contratto, test o pipeline di release
Rischio	Scambiare un numero disponibile per una prova sufficiente

La formalizzazione e solida quando un altro analista può riprodurre la logica, criticare le assunzioni e ottenere la stessa decisione partendo dagli stessi dati.

Esempio o caso studio

Una PR modifica la definizione di is_active_customer e impatta tre mart e due dashboard executive. Il caso mostra perché la code review deve guardare lineage, owner, test e comunicazione del cambiamento, non solo se il modello compila.

Evidenza osservata	Lettura prudente	Azione consigliata
Il numero migliora	Potrebbe essere effetto reale o variazione normale	Cercare confronto e segmento
Un segmento cambia più degli altri	La media aggregata nasconde una differenza	Separare coorti o casi d’uso
Il costo cresce insieme al risultato	L’impatto va letto sul margine	Stimare trade-off e sostenibilità

Lab / esercizio

Livello base

Scrivi una scheda di una pagina per Git workflow, code review e collaborazione tecnica: decisione da supportare, metrica primaria, baseline, rischio principale e azione se il segnale e confermato.

Livello intermedio

Costruisci una tabella con tre segmenti, periodi o scenari. Per ciascuno indica cosa cambia, quale spiegazione alternativa e plausibile e quale controllo useresti prima di raccomandare un azione.

Livello research-grade

Prepara un decision memo: ipotesi, dati richiesti, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio dopo la decisione.

Dataset e materiali consigliati

Usa dbt, warehouse, sorgenti CRM, eventi, marts, semantic layer e lineage. Se non hai accesso a dati reali, crea un dataset sintetico con almeno 200 righe, una dimensione temporale, una dimensione segmento e una metrica di outcome.

Errore tipico da evitare

L’errore più comune e usare Git workflow, code review e collaborazione tecnica come etichetta invece che come processo. Succede quando il team mostra un grafico senza decisione, una metrica senza baseline, o una conclusione senza indicare quale assunzione potrebbe invalidarla.

La domanda di controllo è: se questo risultato fosse instabile, quale scelta sbaglierei? Se la risposta non è concreta, manca ancora il collegamento tra analisi e azione.

Quiz o checkpoint

1. Quale decisione concreta dovrebbe migliorare questa lezione?
2. Quale unità di analisi rende il problema misurabile?
3. Quale baseline useresti per evitare una lettura ingenua?
4. Quale errore tipico potrebbe cambiare la conclusione?
5. Quale output consegneresti a uno stakeholder non tecnico?

Riepilogo operativo

Git workflow, code review e collaborazione tecnica diventa utile quando produce una decisione più chiara, non quando aggiunge terminologia. Usa il framework problema, modello, formalizzazione, esempio, lab e checkpoint per trasformare la lezione in pratica verificabile. Categoria: Decisione. Difficoltà: advanced. Tempo stimato: 18 min.