Cos'è una pull request e come si scrive bene

La pull request è il punto in cui il lavoro individuale diventa lavoro di squadra: proponi delle modifiche, qualcuno le guarda, si discute, si integra. È anche una delle cose che chi arriva al primo lavoro fa peggio — non per incapacità tecnica, ma perché nessuno spiega come si confeziona una proposta di modifica leggibile. In questo articolo trovi come si fa.

Cos'è

Una pull request è una proposta di integrare le modifiche di un ramo in un altro, aperta a revisione prima di essere accettata.

Il nome cambia a seconda della piattaforma — pull request su GitHub, merge request su GitLab — ma il concetto è identico: non stai unendo il codice, stai chiedendo che venga unito.

Non è una funzione di Git: è una funzione delle piattaforme che ci stanno sopra. Git conosce i rami e le unioni; la revisione, i commenti e le approvazioni sono un livello aggiunto.

Il flusso

1. Crei un ramo dal principale
2. Ci lavori e fai commit
3. Invii il ramo al server condiviso
4. Apri la pull request, indicando cosa vuoi integrare e dove
5. I controlli automatici partono (test, verifiche di stile) — di solito tramite GitHub Actions
6. Qualcuno la revisiona e commenta
7. Rispondi ai commenti e correggi
8. Viene approvata e integrata
9. Il ramo si cancella

Il punto 5 vale la pena presidiarlo: una pull request che arriva alla revisione con i test già rossi fa perdere tempo a tutti. Controlla che i controlli passino prima di chiedere a qualcuno di guardarla.

Come scriverne una che funziona

Qui sta la differenza tra una revisione veloce e una che si trascina per giorni.

Regola numero uno: piccola

È il fattore che pesa più di tutti gli altri messi insieme.

Una pull request da 50 righe viene revisionata con attenzione in dieci minuti. Una da 2.000 righe viene guardata di sfuggita e approvata per stanchezza — cioè non revisionata affatto.

Esiste un fenomeno noto e piuttosto ironico: su una modifica piccola ricevi cinque commenti puntuali, su una enorme ricevi "mi sembra ok". Più codice proponi, meno attenzione riceve per riga.

Se il lavoro è grosso, spezzalo: prima il refactoring, poi la funzionalità. Due proposte separate vengono revisionate meglio di una doppia.

Un solo scopo

Una pull request deve fare una cosa. Se il titolo contiene una "e" — "aggiunge il login e sistema il footer" — probabilmente sono due proposte.

Mescolare una correzione con una riformattazione automatica di tutto il file è particolarmente controproducente: la modifica vera si perde tra centinaia di righe cambiate solo nell'indentazione.

La descrizione

È la parte che fa risparmiare più tempo a chi revisiona:

Cosa fa — in due righe, in italiano, non un elenco di file toccati.

Perché — il problema che risolve, con un riferimento alla segnalazione se c'è.

Come — solo se hai preso una decisione non ovvia. "Ho usato una cache in memoria invece di Redis perché i dati sono pochi e scadono in fretta" previene tre giri di commenti.

Come si verifica — i passaggi per provarlo. Chi revisiona non deve indovinare.

Cosa NON è incluso — se hai lasciato qualcosa di proposito, dillo. Evita commenti su cose che sai già.

Una schermata o un video breve, se la modifica è visibile, valgono più di qualunque descrizione.

Rileggi la tua stessa proposta

È l'abitudine con il ritorno più alto in assoluto, e quasi nessuno la ha.

Prima di chiedere una revisione, guarda tu il confronto riga per riga. Troverai codice di prova dimenticato, commenti scritti a te stesso, file toccati per sbaglio, un console.log rimasto. Sono tutte cose che, trovate da qualcun altro, costano un giro di commenti e mezza giornata.

Come rispondere ai commenti

Rispondi a tutti, anche solo con "fatto". Un commento senza risposta lascia chi revisiona nel dubbio se sia stato letto.

Se non sei d'accordo, spiegalo. Una pull request è una conversazione tecnica, non un esame. Se hai una ragione, dilla — chi revisiona può non avere il contesto che hai tu.

Non prenderla sul personale. I commenti riguardano il codice. È una distinzione facile da enunciare e difficile da interiorizzare all'inizio, ma è quella che rende la revisione utile invece che fastidiosa.

Fai commit separati per le correzioni, così chi revisiona vede cosa è cambiato dal suo commento invece di rileggere tutto. Sul come scriverli, la convenzione più diffusa è in conventional commits.

Se sei tu a revisionare

Vale la pena dirlo, perché prima o poi capita:

Sii tempestivo. Una proposta ferma tre giorni blocca una persona. Meglio una revisione parziale oggi che una completa venerdì.

Distingui l'obbligatorio dal preferibile. "Questo va cambiato perché c'è un bug" e "io lo scriverei diversamente" non sono la stessa cosa, e vale la pena segnalarlo esplicitamente.

Fai domande invece di dare ordini. "C'è un motivo per non usare X qui?" apre una conversazione; "usa X" la chiude.

Riconosci le cose fatte bene. Una revisione che contiene solo critiche è demoralizzante, e per chi è all'inizio fa parecchia differenza.

Non bloccare per gusto personale. Se il codice funziona ed è leggibile, lo stile che avresti scelto tu non è un motivo per rifiutare.

Perché conta più di quanto sembri

La revisione non serve solo a trovare errori — anzi, i bug che intercetta sono spesso pochi, perché i test ne prendono di più.

Serve soprattutto a due cose:

Diffondere la conoscenza. Se una sola persona sa come funziona una parte del sistema, quella parte è a rischio. La revisione fa sì che almeno due persone abbiano visto ogni pezzo.

Mantenere la coerenza. È il meccanismo attraverso cui un codice scritto da cinque persone continua a sembrare scritto da una.

E per chi è all'inizio, è probabilmente il canale di apprendimento più efficace che esista: qualcuno di più esperto guarda il tuo codice concreto e ti dice cosa migliorare. Vale più di molti corsi.

In sintesi

Una pull request è una proposta di integrare delle modifiche, aperta a revisione. Non è una funzione di Git ma delle piattaforme che ci stanno sopra.

La regola che conta più di tutte: falla piccola. Una modifica da 50 righe viene revisionata davvero; una da 2.000 viene approvata per stanchezza.

Poi: uno scopo solo, una descrizione che spiega cosa, perché e come si verifica, e rileggere la propria proposta prima di inviarla — l'abitudine che risparmia più tempo a tutti.

E il motivo per cui esiste non è tanto trovare bug: è diffondere la conoscenza nel team e mantenere il codice coerente. Per chi inizia, è anche il modo più veloce per migliorare davvero.

Se il flusso dei rami non ti è ancora chiaro, la base è in cos'è il version control.