La magia dei Pull Request

1. Dallo merge alla proposta: perché servono i Pull Request?

Nella lezione precedente abbiamo imparato a unire (merge) i rami sul nostro computer locale. Questo funziona bene quando lavori da solo. Ma cosa succede se sul progetto lavora un intero team? Se ciascuno integrerà i propri cambiamenti direttamente sul ramo principale main, presto regnerà il caos: qualcuno potrebbe aggiungere per errore codice con bug, rompere la build o cancellare parti importanti del lavoro di un collega.

Per evitare questo, nello sviluppo di squadra si adotta un altro approccio. Invece di unire subito i cambiamenti, si crea una proposta di merge. Questa proposta si chiama Pull Request (abbreviato PR) oppure, su alcune piattaforme, Merge Request.

Pull Request è una richiesta ufficiale: “Per favore, prendi (pull) i miei cambiamenti dal mio ramo e aggiungili (merge) al ramo principale”. Ma non è solo una richiesta: è una piattaforma per discutere, controllare e migliorare il codice prima che entri in main.

2. Flusso di lavoro standard con i Pull Request

Analizziamo passo passo come si presenta il tipico flusso di lavoro quando si sviluppa una nuova funzionalità.

Prima di creare un ramo per una nuova task, assicurati di aver inviato tutti i tuoi commit completati con push e di aver aggiornato (Update Project) il ramo principale main.

Altrimenti i tuoi commit locali “dimenticati” dal main potranno finire per errore nel nuovo Pull Request, creando confusione per i colleghi.

Passo 1. Crea un ramo per la nuova task.

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

Passo 2. Applica le modifiche e invia il tuo ramo su GitHub.

Nel nuovo ramo crea il file CONTRIBUTING.md (dopo la creazione clicca su Add) e scrivi al suo interno un messaggio per gli altri sviluppatori. Dopo di che fai Commit and Push con un messaggio chiaro, per esempio: docs: Add contribution guide.

Questo è un passaggio chiave! Il Pull Request si crea sulla base di un ramo che esiste già sul server remoto. Quindi, prima di creare il PR, assicurati di avere inviato (push) il tuo nuovo ramo su GitHub.

3. Creare un Pull Request da IntelliJ IDEA

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

Passo 1. Apri la scheda Pull Requests.

Nel pannello laterale sinistro dell'IDE trova la scheda (Tool Window) Pull Requests. Aprila e clicca sull'icona + (o sul pulsante Create Pull Request) per creare un nuovo PR.

Passo 2. Compila i dati per il PR.

L'IDE aprirà automaticamente un'interfaccia comoda. Il tuo compito è compilarla correttamente. Vediamo i campi principali:

1. Titolo: l'IDE spesso inserisce qui il nome del ramo o il testo dell'ultimo commit. Assicurati che il titolo sia breve, chiaro e rifletta il contenuto delle modifiche.
2. Descrizione: qui spieghi in dettaglio ai colleghi cosa hai fatto e perché.
3. Reviewer (Reviewers): qui scegli uno o più colleghi che devono revisionare il tuo codice. Nel progetto didattico saltiamo questo passo, ma nel lavoro reale è obbligatorio.
4. Assegnatari (Assignees): di solito qui indichi te stesso. Questo significa che sei l'autore e il principale responsabile della task e delle modifiche successive dopo il review.

Dopo aver compilato tutti i campi, premi tranquillamente Create Pull Request.

4. Code review: verifica e discussione

Dopo la creazione del PR inizia la fase più importante: la code review. I tuoi colleghi possono aprire il 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 su una riga di codice, riceverai una notifica e potrai rispondere senza passare al browser.

Cosa fare se ti chiedono di apportare modifiche?

Molto semplice! Non serve creare un nuovo PR. Applica le modifiche richieste nel codice sul tuo ramo corrente, fai un nuovo commit e invialo. Il Pull Request su GitHub si aggiornerà automaticamente aggiungendo i nuovi commit alla discussione esistente.

5. Completamento: merge e rimozione del ramo

Quando tutte le osservazioni sono state risolte e il team approva le modifiche (ricevi l'approvazione), il Pull Request può essere unito. Di solito lo fa uno sviluppatore senior o tu stesso, se hai i permessi nel repository.

Passo 1. Merge

Il merge avviene solitamente sul sito di GitHub o direttamente dalla finestra Pull Requests nell'IDE. Su GitHub, sotto il tuo PR comparirà un grande pulsante verde Merge pull request. Dopo averlo cliccato il tuo codice diventerà parte del ramo principale main.

Passo 2. Eliminazione del ramo.

Dopo il merge il tuo ramo feature non è più necessario e va eliminato per non ingombrare il repository. GitHub ti proporrà automaticamente di farlo mostrando il pulsante Delete branch.

Non dimenticare anche di eliminare la copia locale del ramo nella tua IDE e di fare Update Project sul ramo main per scaricare i risultati del merge sul tuo computer.

6. Tre regole per un buon commit

Un buon commit non è solo un messaggio corretto, ma anche un contenuto adeguato. Per mantenere la cronologia delle modifiche pulita, utile e professionale, segui queste tre semplici regole.

Regola 1: scrivi messaggi chiari secondo uno standard

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

<tip>: <kratkoe opisanie>

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

• feat: (feature) — per nuove funzionalità.
• fix: — per correzioni di 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 nuove funzionalità né risolvono bug.
• test: — per l'aggiunta o la correzione dei test.
• chore: — per attività di routine non legate al codice (aggiornamento dipendenze, configurazione build).

Esempi:

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

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

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

Non cercare di mettere in un solo commit la correzione di un bug, l'aggiunta di una nuova funzionalità e il refactor di codice vecchio. Un commit del genere è molto difficile da revisionare e quasi impossibile da annullare senza dolore, se qualcosa va storto.

Ogni commit dovrebbe risolvere una sola specifica attività.

• Male: un commit con messaggio "Update user page" che aggiunge il campo avatar, corregge la validazione del nome e cambia il colore dei pulsanti.
• Bene: tre commit distinti:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Se ti accorgi di aver modificato troppo in un singolo file, IntelliJ IDEA ti permette di non committare l'intero file per intero! Nella finestra Commit puoi espandere il file e selezionare solo i chunk di codice che appartengono a una specifica attività logica.

Regola 3: il commit non deve rompere il progetto

Ogni commit nel ramo 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 a controlli manuali è rischioso.

Qui entra in gioco l'automazione. In questo corso non configureremo i processi automatici, ma dovresti sapere come funzionano nei progetti reali. I team moderni usano sistemi di integrazione continua (Continuous Integration, CI), come ad esempio GitHub Actions.

Come funziona?

Scrivi codice e test. Poi tu o il DevOps configurate uno script (workflow) direttamente su GitHub. Ora, non appena fai push sul tuo Pull Request, succede la magia:

1. GitHub Actions rileva l'evento e avvia il tuo script sul server remoto.
2. Esso automaticamente "builda" il progetto e esegue tutti i test che hai scritto.
3. Se tutti i test passano, accanto al tuo commit su GitHub compare una spunta verde. Questo è un segnale per tutto il team che le tue modifiche sono sicure.
4. Se anche un solo test fallisce, vedrai una croce rossa. Non è consentito unire un PR del genere nel ramo principale fino alla correzione degli errori.

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

            subgraph Workflow
            C -- "Esecuzione" --> D[Esecuzione_test]
            D --> E[Riuscito]
            D --> F[Non_riuscito]
            end

            subgraph Notifications
            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
        

Si possono configurare notifiche. Se i test falliscono, GitHub Actions può inviare una mail a te o a tutto il team. Questo approccio crea una cultura in cui i test non sono una formalità ma una parte integrante dello sviluppo, e ciascuno è responsabile della qualità del proprio codice.