Git workflow, code review, and technical collaboration

Quando più persone lavorano sugli stessi modelli che alimentano dashboard critici, il workflow Git smette di essere un dettaglio e diventa parte della qualità del dato. Pull request, revisioni, naming e ownership entrano nel lavoro quotidiano dell’analytics engineer, perché ogni modifica può cambiare un numero che qualcun altro userà per decidere.

Il problema da risolvere

In analytics engineering il compito è trasformare dati grezzi in modelli testati, documentati e riusabili dal business. Non basta scrivere SQL corretto: serve che ogni modifica sia tracciabile, verificabile e che porti a decisioni più affidabili. Il segnale che il processo è diventato competenza è sempre lo stesso: sai dire quale decisione cambia, quale dato osservi e quale errore vuoi evitare. Senza quei tre punti, hai una procedura ma non una pratica.

Un modello per restare sull’obiettivo

Phase	What to clarify	Output
Question	Which real choice needs improvement?	Decision to make
Measure	Which observable signal represents the problem?	Metric or source data
Control	Which baseline makes the result interpretable?	Credible comparison
Action	What changes after the analysis?	Next operational step

Lo schema tiene il focus sull’obiettivo: ogni attività tecnica, anche una code review, deve rafforzare almeno uno di questi punti.

Come rendere analizzabile il workflow

Per ragionare sul workflow conviene partire dall’unità di lavoro, che può essere una source, un model, un test, un mart, una metrica o un’esposizione. La leghi a una metrica osservabile come freshness, lineage, copertura dei test, costo del modello o fiducia degli stakeholder, e dichiari la decisione attesa, che riguarda un modello dbt, un semantic layer, un contratto, un test o una pipeline di release. Il rischio costante è scambiare un numero disponibile per una prova sufficiente.

Element	Requested specification
Unit of analysis	source, model, test, mart, metric or exposure
Primary signal	freshness, lineage, test coverage, model cost, and stakeholder trust
Baseline	Previous period, comparable group, benchmark, or counterfactual scenario
Decision	dbt model, semantic layer, contract, test or release pipeline
Risk	Mistaking an available number for sufficient proof

La formalizzazione regge quando un altro analista riprende la stessa logica, ne critica le assunzioni e arriva alla stessa decisione partendo dagli stessi dati.

Caso studio: una PR che tocca tre mart

Una pull request modifica la definizione di is_active_customer e impatta tre mart e due dashboard executive. È il caso che mostra perché la code review deve guardare lineage, ownership, test e comunicazione del cambiamento, non solo se il modello compila. Una modifica innocua in apparenza può spostare un numero su cui un dirigente baserà una scelta.

Observed evidence	Cautious interpretation	Recommended action
The number improves	Could be a real effect or normal variation	Cercare confronto e segmentazione
One segment changes more than others	The aggregated average hides a difference	Separate cohorts or use cases
Cost grows along with the result	Impact must be read on the margin	Estimate trade-offs and sustainability

Git workflow per progetti dbt

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

main ──────────────────────────────────────────────► (production)
  │
  ├── feature/new-mrr-model ──► PR ──► review ──► merge
  │
  ├── fix/campaign-cost-bug ──► PR ──► review ──► merge
  │
  └── staging ──► (automatic deploy to test environment)

Le regole essenziali sono poche e vanno rispettate sempre.

1. Mai commitare direttamente su main: ogni modifica passa da branch e pull request.
2. Every PR runs dbt build su uno schema separato creato dal CI/CD per isolare i cambiamenti.
3. La PR si può mergiare solo se il build è verde e almeno un reviewer ha approvato.
4. Il merge su main fa partire il deploy in produzione o in staging.

Code review per modelli dati

La code review di un modello dbt ha priorità diverse rispetto al codice applicativo. Verifica che i test siano presenti e sufficienti, con almeno un not_null sulla primary key. Controlla che la logica di business stia nel layer corretto, perché regole complesse non vanno nei modelli staging. Assicurati che il naming sia chiaro e coerente con le convenzioni, che ci sia documentazione YAML con descrizioni e test sulle colonne critiche, e che la query regga i volumi di produzione.

In pratica un reviewer scorre una checklist breve: test not_null e unique sulla primary key, logica di business nel layer giusto, naming di file, modello e colonne conforme alle convenzioni, documentazione YAML presente, query scalabile e DAG aciclico.

Conflict management on dbt models

I conflitti qui sono più rischiosi che altrove, perché Git non interpreta il SQL e non capisce se due modifiche sono compatibili. Per ridurli conviene tenere i modelli piccoli e con una responsabilità singola, così la superficie di conflitto si restringe, e dare a ogni sviluppatore uno schema dedicato tramite i profili, in modo da isolare gli ambienti di lavoro.

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

Quality control

Prima di applicare workflow e code review, verifica completezza, duplicati, timezone, definizioni cambiate e segmenti esclusi. Molte analisi falliscono perché il dato di partenza non rappresenta il comportamento atteso, e nessuna revisione di codice lo recupera.

Interpretation by segments

La media aggregata è solo un punto di partenza. Segmenta per canale, coorte, piano, paese, device e maturità dell’utente. Quando i segmenti si muovono in direzioni opposte, la media inganna e porta a decisioni sbagliate.

Operational decision

Ogni analisi deve chiudersi con una scelta concreta, che sia continuare, fermare, iterare, investire, rimuovere o approfondire. Se il workflow e la code review non spostano nessuna decisione, manca il collegamento tra metrica e azione.

Esercizio guidato

Al livello base scrivi una scheda sintetica per il workflow e la code review: decisione da supportare, metrica principale, baseline, rischio e azione prevista. Al livello intermedio costruisci una tabella con tre segmenti o scenari, indicando per ciascuno cosa cambia, una spiegazione alternativa e il controllo che useresti prima di agire. Al livello research-grade prepara un decision memo con ipotesi, dati richiesti, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio. Per gli strumenti usa dbt, il warehouse, le sorgenti CRM, gli eventi, i marts, il semantic layer e il lineage; se non hai dati reali, costruisci un dataset sintetico di almeno 200 righe con dimensione temporale, segmenti e metrica di outcome.

L’errore tipico da evitare

Il rischio è usare il workflow e la code review come etichetta invece che come processo. Succede quando si mostra un grafico senza decisione, una metrica senza baseline o una conclusione che non dichiara quali assunzioni potrebbero invalidarla. La domanda chiave resta una: se questo risultato fosse instabile, quale scelta sbaglierei? Se la risposta non è concreta, manca il collegamento tra analisi e azione.

Checkpoint

Prima di chiudere, verifica di saper rispondere a queste domande.

1. Which concrete decision should this lesson improve?
2. Which unit of analysis makes the problem measurable?
3. Which baseline would you use to avoid a naive reading?
4. Which typical mistake could change the conclusion?
5. Which output would you deliver to a non-technical stakeholder?

Summary

Workflow Git e code review servono solo se producono decisioni più chiare e affidabili, non come terminologia. Il percorso problema, modello, formalizzazione, esempio, lab e checkpoint trasforma la lezione in una pratica che puoi verificare.

---

References: GitLab Handbook (2024), dbt Labs (2023), Accelerate (Forsgren et al., 2018).