Pull Request: cos'è, processo di creazione e code review

Cos'è un Pull Request?

Pull Request (PR) è una richiesta formale per includere modifiche da un ramo all'altro all'interno di un sistema di controllo versione distribuito. Il PR è un elemento centrale dello sviluppo collaborativo sulle piattaforme GitHub, GitLab e Bitbucket, combinando discussione del codice, test automatizzati e processo di approvazione delle modifiche.

Il nome “Pull Request” riflette l'essenza dell'operazione: uno sviluppatore chiede (request) al proprietario del repository di “pullare” (prelevare) le sue modifiche. Il termine è stato introdotto da GitHub nel 2008 — prima di allora, un meccanismo simile esisteva sotto forma di patch e merge requests (termine di GitLab). Oggi il PR è lo standard de facto per lo sviluppo di team con Git.

Secondo GitHub Octoverse, 2025, l'89% dei progetti open-source richiede la creazione di un PR per apportare modifiche. Nello sviluppo aziendale, questa cifra raggiunge il 95%. Il PR è diventato non solo uno strumento tecnico, ma parte della cultura di sviluppo: attraverso i PR avvengono il trasferimento di conoscenze, il rilevamento di bug e l'allineamento delle decisioni architetturali.

Componenti di un Pull Request

Un PR tipico è composto da titolo, descrizione, elenco dei file modificati (diff), commenti dei revisori e stati dei controlli CI. Ogni PR è collegato a un ramo sorgente e a un ramo di destinazione specifici e dopo l'unione può essere eliminato automaticamente.

Come creare un Pull Request

Creare un PR inizia con la pubblicazione di un ramo feature nel repository remoto. Dopo il push, lo sviluppatore apre un PR tramite l'interfaccia della piattaforma o tramite CLI (gh, glab). Vediamo il processo usando GitHub come esempio.

Push del ramo e apertura del PR

Il primo passo è eseguire il push del ramo feature nel repository remoto e creare un Pull Request tramite l'interfaccia web o la riga di comando.

# Creare e pushare un ramo feature
git checkout -b feature/biometric-auth
git add src/auth/
git commit -m "feat: add biometric authentication"
git push -u origin feature/biometric-auth

# Creare un PR tramite GitHub CLI
gh pr create --title "feat: add biometric authentication" \
  --body "Implements fingerprint and face recognition login.
  Closes #142" \
  --base develop

Dopo aver creato un PR, GitHub esegue automaticamente le pipeline CI (GitHub Actions), verifica la presenza di conflitti con il ramo di destinazione e invita i revisori. Il modello di descrizione del PR può essere configurato tramite .github/PULL_REQUEST_TEMPLATE.md in modo che tutti i PR contengano le sezioni richieste: obiettivo, modifiche, test, attività correlate.

Descrizione e tagging

Una descrizione di PR di qualità include: un collegamento all'attività (issue/ticket), una breve descrizione delle modifiche, istruzioni per il test e un elenco delle modifiche correlate. Le etichette (bug, feature, refactoring) aiutano a categorizzare il PR, mentre assignees e reviewers vengono assegnati automaticamente tramite CODEOWNERS.

# Assegnare revisori tramite CODEOWNERS (file nella radice del repository)
# Esempio .github/CODEOWNERS:
# src/auth/ @team-auth @senior-dev
# src/api/ @team-backend
# *.kt @kotlin-team

# Creare un PR assegnando revisori tramite gh cli
gh pr create --reviewer "team-auth" --label "feature"

CODEOWNERS è un meccanismo standard di GitHub/GitLab per assegnare automaticamente i revisori in base ai file modificati. Ad esempio, qualsiasi modifica nella directory src/auth/ assegna automaticamente team-auth e senior-dev come revisori. Questo accelera il processo e garantisce che le persone giuste vedano il PR.

Aggiornamento del PR in base alle revisioni

Dopo aver ricevuto i commenti del revisore, lo sviluppatore apporta correzioni nello stesso ramo feature e pusha nuovi commit — il PR si aggiorna automaticamente. È importante non riscrivere la cronologia (rebase) in un ramo feature pubblicato se il PR è già aperto, poiché questo rompe i collegamenti a commit specifici nei commenti.

# Apportare modifiche in base ai commenti del revisore
git checkout feature/biometric-auth
# correggere il codice
git commit -m "fix: handle biometric timeout per review"
git push

# il PR si aggiornerà automaticamente
# Dopo l'approvazione — unire il PR tramite l'interfaccia GitHub

Il processo di code review

Il code review è un elemento centrale di un Pull Request. Il revisore verifica le modifiche per correttezza, stile del codice, sicurezza e coerenza architetturale. Una revisione di qualità non solo previene i bug, ma diffonde la conoscenza della base di codice all'interno del team.

Le Engineering Practices di Google (2025) raccomandano i seguenti principi di code review: il revisore deve comprendere il contesto delle modifiche, fornire raccomandazioni specifiche invece di osservazioni generiche e separare i commenti tecnici da quelli stilistici. Il tempo di revisione non deve superare le 24 ore dal momento della creazione del PR.

Per lo sviluppo mobile, il code review include controlli specifici: compatibilità con targetSdk, corretta gestione del lifecycle (Android) / view lifecycle (iOS), assenza di perdite di memoria (LeakCanary, Instruments), supporto del tema scuro e localizzazione. Questi controlli possono essere automatizzati tramite linter e Detekt/ktlint.

Tipi di commenti

Le piattaforme PR supportano tre tipi di commenti: generali (sull'intero PR), in linea (su una specifica riga di codice) e suggerimenti (con codice di sostituzione). I suggerimenti consentono di applicare la modifica con un clic, accelerando il processo e riducendo il numero di iterazioni.

Dopo che tutti i commenti sono risolti e i controlli CI sono superati, il revisore invia un'approvazione (Approved). Il PR può essere unito. GitHub e GitLab supportano le regole di protezione dei rami: numero di approvazioni richiesto, controlli CI obbligatori e divieto di push in main senza PR. Per i progetti mobile, la protezione dei rami include anche la verifica del build: un PR non può essere unito se l'applicazione non compila (gradle build failed / xcodebuild failed).

Risoluzione dei conflitti nel PR

I conflitti di unione in un Pull Request sono una situazione comune nel lavoro di squadra attivo. Le piattaforme offrono la risoluzione dei conflitti tramite l'interfaccia web (per conflitti semplici) o raccomandano di risolverli localmente. GitHub Actions verifica automaticamente la possibilità di unione a ogni push nel ramo feature e contrassegna il PR come in conflitto se l'unione non è possibile.

Best practice per Pull Request

I Pull Request efficaci accelerano il code review e riducono il numero di bug. Uno studio di SmartBear (2025) ha mostrato che i PR fino a 200 righe di codice ricevono 2 volte più commenti significativi rispetto ai PR con oltre 1000 righe e il tempo di revisione si riduce di 3 volte.

• PR piccoli — la dimensione ottimale è 100–300 righe. Suddividete i PR grandi in parti logiche: ogni PR risolve un compito. Questo semplifica la revisione e riduce la probabilità di conflitti
• Descrizione chiara — titolo secondo Conventional Commits (feat:, fix:, refactor:), il corpo contiene “cosa e perché” invece di “come” (il codice parla da sé). Modello: obiettivo → modifiche → test → issue correlate
• Feedback rapido — revisione entro 24 ore. Se un PR aspetta più di un giorno, il team perde il contesto e il numero di conflitti di unione aumenta
• Automazione — linter, formattatori e test devono essere eseguiti automaticamente alla creazione di un PR. Non consentite l'unione di PR con controlli CI rossi
• Draft PR — utilizzare per la discussione anticipata dell'architettura. Il Draft PR non richiede revisione e non può essere unito, ma consente di mostrare il codice ai colleghi in una fase iniziale

Pratiche aggiuntive: non create PR il venerdì sera (nessuno farà la revisione fino al lunedì), richiedete la revisione a 1–2 persone (più persone rallentano il processo senza migliorare la qualità), utilizzate squash merge per comprimere la cronologia prima dell'unione. Per i progetti mobile, si raccomanda anche di aggiungere un collegamento al build di test (Firebase App Distribution / TestFlight) nella descrizione del PR in modo che il revisore possa verificare le modifiche nell'applicazione in esecuzione.

Pull Request su diverse piattaforme

Le principali piattaforme per lavorare con i Pull Request sono GitHub, GitLab e Bitbucket. Nonostante il concetto condiviso, ciascuna ha caratteristiche da considerare nella scelta di uno strumento per il team.

GitHub è la piattaforma più popolare con la community più grande, Actions per CI/CD e un vasto ecosistema di applicazioni (GitHub Marketplace). GitLab si distingue per CI/CD integrato e capacità di distribuzione self-hosted completa. Bitbucket è strettamente integrato con Jira e l'ecosistema Atlassian, popolare negli ambienti aziendali.

Per lo sviluppo mobile, la scelta della piattaforma è spesso determinata dalle capacità CI/CD: GitHub Actions supporta i runner macOS per i build iOS, GitLab ha runner integrati per iOS/Android, Bitbucket si integra bene con Firebase Test Lab. Indipendentemente dalla piattaforma, il processo PR rimane lo stesso: ramo → revisione → CI → unione.