La magia delle Pull Request

1. Dalla fusione alla proposta: a cosa servono le Pull Request?

Nella lezione precedente abbiamo imparato a unire (merge) i branch sul proprio computer locale. Questo funziona benissimo quando lavori da solo. Ma cosa succede se su un progetto lavora un intero team? Se ognuno unisse le proprie modifiche direttamente nel branch principale main, ben presto inizierebbe il caos: qualcuno potrebbe aggiungere per sbaglio codice con errori, rompere la build o eliminare una parte importante del lavoro di un collega.

Per evitarlo, nello sviluppo in team si adotta un approccio diverso. Invece di unire subito le modifiche, crei una proposta di fusione. Questa proposta si chiama Pull Request (in breve PR) o, su alcune piattaforme, Merge Request.

Pull Request — è una richiesta ufficiale: «Per favore, preleva (pull) le mie modifiche dal mio branch e uniscile (merge) al branch principale». Ma non è solo una richiesta, è un vero e proprio spazio per la discussione, la verifica e il miglioramento del codice prima che finisca in main.

2. Flusso di lavoro standard con le Pull Request

Vediamo passo per passo come appare il flusso tipico durante la creazione di una nuova funzionalità.

Prima di creare un branch per una nuova attività, assicurati di inviare tutti i tuoi commit completati (push) e di aggiornare (Update Project) il branch principale main.

Altrimenti tutti i tuoi commit locali «dimenticati» da main finiranno accidentalmente nella nuova Pull Request, creando confusione per i colleghi.

Passo 1. Crea un branch per la nuova attività.

Come prima, ogni nuovo lavoro inizia creando un branch separato. Supponiamo di voler aggiungere al nostro progetto un file con le regole per i contributor. Creiamo il branch feature/add-contribution-guide.

Passo 2. Apporta le modifiche e invia il tuo branch su GitHub.

Nel nuovo branch crea il file CONTRIBUTING.md (dopo la creazione premi Add) e scrivi al suo interno un messaggio per gli altri sviluppatori. Dopo di ciò esegui Commit and Push con un messaggio chiaro, ad esempio: docs: Add contribution guide.

Questo è un passaggio chiave! La Pull Request si basa su un branch che esiste già sul server remoto. Quindi, prima di creare la PR, devi inviare (push) il tuo nuovo branch su GitHub.

3. Creare una Pull Request da IntelliJ IDEA

Ora che il tuo branch è su GitHub, puoi creare la Pull Request.

Passo 1. Apri la scheda Pull Requests.

A sinistra nell’IDE si trova la scheda Pull Requests. Aprila e fai clic sull’icona + per creare una nuova PR.

Passo 2. Compila i dati della PR.

L’IDE aprirà automaticamente un’interfaccia comoda per creare la Pull Request. Il tuo compito è compilarla correttamente. Vediamo i campi principali:

1. Titolo: l’IDE spesso inserisce qui il nome del branch, ma è una cattiva pratica. Il titolo deve essere breve, chiaro e riflettere l’essenza delle modifiche, come un buon messaggio di commit.
2. Descrizione: qui spieghi che cosa e perché hai fatto.
3. Revisori: qui selezioni uno o più colleghi che devono verificare il tuo codice. Nel progetto didattico salteremo questo passaggio, ma nel lavoro reale è obbligatorio.
4. Assegnatari: di solito qui indichi te stesso. Significa che sei l’autore e il principale responsabile di questa attività e delle modifiche dopo la review.

Una volta compilati tutti i campi, premi Create Pull Request senza esitazione.

4. Code review: verifica e discussione

Dopo la creazione della PR inizia la fase più importante — la code review. I tuoi colleghi possono aprire la tua PR, vedere tutte le modifiche e lasciare commenti.

Puoi vedere tutte le discussioni direttamente nell’IDE nella scheda Pull Requests. Se qualcuno lascia un commento, riceverai una notifica.

Cosa fare se ti chiedono di apportare modifiche?

Molto semplice! Non serve creare una nuova PR. Apporta semplicemente le modifiche necessarie al codice nello stesso branch, crea un nuovo commit e invialo (push). La Pull Request su GitHub si aggiornerà automaticamente aggiungendo i tuoi nuovi commit.

5. Conclusione del lavoro: merge e cancellazione del branch

Quando tutti i commenti sono stati risolti e il team approva le tue modifiche, la Pull Request può essere unita. Di solito lo fa uno sviluppatore senior oppure tu stesso, se hai i permessi.

Passo 1. Merge

Il merge avviene più spesso sul sito di GitHub. Lì, sotto la tua PR, apparirà il grande pulsante verde Merge pull request. Dopo averlo premuto il tuo codice diventerà parte del branch principale main.

Passo 2. Eliminazione del branch.

Dopo il merge il tuo branch `feature` non serve più e conviene eliminarlo per non sporcare il repository. GitHub lo proporrà automaticamente, mostrando il pulsante Delete branch.

Non dimenticare di eliminare anche la copia locale del branch nella tua IDE, per mantenere l’ordine. Puoi farlo dallo stesso menu di gestione dei branch.

6. Tre regole del commit

Un buon commit non è solo un messaggio corretto, ma anche un contenuto appropriato. Perché la tua cronologia delle modifiche sia pulita, utile e professionale, attieniti a tre semplici regole.

Regola 1: scrivi messaggi chiari seguendo uno standard

I tuoi commit sono messaggi che invii al tuo team e a te stesso nel futuro. Una cronologia piena di messaggi «fix» o «update» è assolutamente inutile. Lo standard più diffuso si chiama Conventional Commits. Propone la seguente struttura:

<tipo>: <breve descrizione>

Tipo — è una parola breve che descrive la categoria delle tue modifiche:

• feat: (feature) — per una nuova funzionalità.
• fix: — per correggere un bug.
• docs: — per modifiche alla documentazione.
• style: — per correzioni di formattazione che non influenzano la logica del codice.
• refactor: — per modifiche al codice che non aggiungono nuova funzionalità e non correggono bug.
• test: — per aggiungere o correggere test.
• chore: — per attività di routine non legate al codice (aggiornamento delle dipendenze, configurazione della build).

Esempi:

• Male: fixed bug
• Bene: fix: Correct user login validation

• Male: readme
• Bene: docs: Update installation instructions

Regola 2: un commit — una sola modifica logica (Atomicità)

Non cercare di far entrare in un unico commit la correzione di un bug, l’aggiunta di una nuova funzione e il refactoring del codice vecchio. Un commit del genere è molto difficile da rivedere e quasi impossibile da annullare senza dolore se qualcosa va storto.

Ogni commit deve risolvere un solo compito specifico.

• Male: un singolo commit con il messaggio «Update user page», che aggiunge il campo per l’avatar, corregge un errore nella validazione del nome e cambia il colore dei pulsanti.
• Bene: tre commit diversi:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Commit piccoli e focalizzati sono molto più semplici da comprendere e gestire.

Regola 3: un commit non deve rompere il progetto

Ogni commit nel branch principale deve lasciare il progetto in stato funzionante. Prima di crearlo devi almeno assicurarti che il codice compili. Ma come essere sicuri di non aver rotto qualcosa in un’altra parte del sistema? Affidarsi solo al controllo manuale è rischioso.

Qui entra in gioco la automazione. In questo corso non configureremo processi automatici, ma devi sapere come funziona nei progetti reali. I team moderni usano sistemi di integrazione continua (Continuous Integration, CI), come GitHub Actions.

Come funziona?

Scrivi il codice e i test. Poi configuri uno script speciale (workflow) direttamente su GitHub. Ora, non appena fai push nella tua Pull Request, succede la magia:

1. GitHub Actions vede questo evento e avvia il tuo workflow.
2. Compila automaticamente il progetto e esegue tutti i test.
3. Se tutti i test vengono superati con successo, accanto al tuo commit su GitHub appare una spunta verde. È un segnale per tutto il team che le tue modifiche sono sicure.
4. Se anche un solo test fallisce, vedrai una croce rossa. Unire una PR del genere nel branch principale è categoricamente vietato.

            graph LR
            subgraph GitHub
            A[Sviluppatore] -- "push" --> B(Repository)
            B -- "Evento: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "Avvio" --> D[Avvio_test]
            D --> E[Successo]
            D --> F[Non riuscito]
            end

            subgraph Notifiche
            F --> G((Email))
            G --> H[Sviluppatore]
            G --> I[Team]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

È possibile configurare le notifiche. Se i test falliscono, GitHub Actions può inviare un’email a te o all’intero team. Questo approccio crea una cultura in cui i test non sono una semplice formalità, ma una parte integrante dello sviluppo, e ognuno è responsabile della qualità del proprio codice.