GitHub Flow e Pull Request workflow

GitHub Flow è un workflow semplice: parti da main, crei un branch, fai commit, apri una pull request, passi review e CI, mergi, cancelli il branch.

È meno estremo del trunk-based puro e molto adatto a team web che rilasciano spesso.

Perché questa lezione conta

La pull request è più di un bottone per fare merge. È il contenitore di discussione, review, test, descrizione del cambiamento e decisione di integrazione.

Un team con PR sane ha meno sorprese: ogni modifica ha contesto, verifiche e responsabilità.

Obiettivo operativo

Alla fine della lezione devi saper eseguire un ciclo GitHub Flow completo e scrivere una checklist PR utile.

Il ciclo

main aggiornato
-> branch breve
-> commit atomici
-> push
-> PR
-> CI
-> review
-> merge
-> delete branch

Comandi:

git switch main
git pull --ff-only
git switch -c feat/profilo-utente
git push -u origin feat/profilo-utente

Poi PR su piattaforma.

Anatomia di una buona PR

Una PR dovrebbe rispondere a:

1. cosa cambia;
2. perché cambia;
3. come è stato verificato;
4. rischi o trade-off;
5. screenshot o video se UI;
6. issue collegata;
7. follow-up non inclusi.

Template:

## Cosa

## Perché

## Verifiche

## Rischi

## Screenshot

Review

La review non è solo trovare bug. Deve controllare:

1. correttezza;
2. sicurezza;
3. test;
4. leggibilità;
5. scope;
6. coerenza con architettura;
7. impatto su deploy.

Commenti utili distinguono bloccante da suggerimento.

Definition of ready e done

Una PR è pronta per review quando:

1. il branch parte da una base ragionevolmente aggiornata;
2. il diff è leggibile;
3. la descrizione spiega il perché;
4. i test locali minimi sono stati eseguiti;
5. non contiene file generati o refactor non richiesti.

Una PR è pronta per merge quando:

1. la CI è verde;
2. i commenti bloccanti sono risolti;
3. il comportamento è verificato;
4. eventuali migrazioni o note deploy sono scritte;
5. la strategia di merge scelta produce una storia comprensibile.

Queste due definizioni evitano PR aperte troppo presto e merge fatti per stanchezza.

Strategie di merge

GitHub Flow può usare:

1. merge commit;
2. squash merge;
3. rebase merge.

Scegli una policy. Se il team usa squash, i commit interni alla PR possono essere più liberi. Se mantiene commit, ogni commit dovrebbe essere pulito.

Quando basta

GitHub Flow funziona bene se:

1. c’è un branch principale;
2. release frequenti;
3. ambiente unico o pochi ambienti;
4. PR piccole;
5. CI affidabile;
6. non devi supportare molte versioni in parallelo.

Se hai release pianificate e supporto multiplo, valuta release branch o GitFlow.

Laboratorio guidato

Su un repo sandbox:

1. crea branch da main;
2. fai due commit;
3. apri PR;
4. compila descrizione completa;
5. simula review con commenti;
6. aggiorna branch;
7. merge con strategia scelta;
8. cancella branch locale e remoto.

Output atteso

Checklist PR:

Branch parte da main aggiornato.
Diff sotto controllo.
Descrizione chiara.
Test indicati.
CI verde.
Review completata.
Merge strategy coerente.
Branch cancellato.

Errori comuni

PR enormi. Rendono review lenta e superficiale.

Descrizione vuota. Costringe il reviewer a dedurre tutto dal diff.

Review opzionale. Allora la PR diventa solo burocrazia.

Branch lasciati aperti. Creano rumore e confusione.

Checklist di verifica

• so aprire PR da branch aggiornato;
• so scrivere descrizione utile;
• so scegliere merge strategy;
• so cancellare branch dopo merge;
• il team distingue commenti bloccanti da suggerimenti.

Esercizi

Base · facile

Descrivi il ciclo del GitHub Flow per un cambiamento.

git switch -c feature/login   # 1. branch da main
# 2. commit
git push -u origin feature/login   # 3. push + apri PR
# 4. review → 5. merge in main → 6. deploy

Intermedio · medio

Spiega il ruolo della pull request come punto di review e di CI, e cosa rappresenta main in questo flusso.

Pull Request = luogo dove:
- girano i test automatici (CI) sul branch
- avviene la code review
- si discute prima di toccare main

main = sempre rilasciabile: ci finisce solo codice rivisto e verde

Sfida · difficile

Confronta GitHub Flow con GitFlow indicando per quali contesti ciascuno è adatto.

GitHub Flow: main + branch di feature + PR. Deploy continuo.
  Adatto a: web app, SaaS, rilasci frequenti, un'unica versione in produzione.

GitFlow: main + develop + feature/* + release/* + hotfix/*.
  Adatto a: software con versioni multiple supportate, rilasci pianificati,
            prodotti distribuiti (desktop, librerie con più release attive).

Collegamenti

• Modulo: Workflow di team — lezione 27 del corso.
• GitFlow è il prossimo confronto per contesti più complessi.