Magia dei Pull Requests

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

Nella lezione precedente abbiamo imparato a fare il merge dei branch sul nostro computer locale. Funziona benissimo quando lavori da solo. Ma cosa succede se su un progetto lavora un'intera squadra? Se ognuno facesse merge dei propri cambiamenti direttamente nel branch principale main, presto regnerebbe il caos: qualcuno potrebbe accidentalmente aggiungere codice con bug, rompere la build o cancellare una parte importante del lavoro di un collega.

Per evitare questo, nello sviluppo di squadra si adotta un approccio diverso. Invece di fare subito il merge, crei una proposta di merge. Questa proposta si chiama Pull Request (abbreviato PR) o, su alcune piattaforme, Merge Request.

Pull Request — è una richiesta ufficiale: "Per favore, prendi (pull) i miei cambiamenti dal mio branch e aggiungili (merge) al branch principale". Ma non è solo una richiesta, è un'intera piattaforma per discutere, verificare e migliorare il codice prima che finisca in main.

2. Flusso di lavoro standard con i Pull Request

Vediamo passo passo come appare il tipico flusso di lavoro quando si crea una nuova funzionalità.

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

Altrimenti tutti i tuoi commit locali "dimenticati" da main potrebbero finire accidentalmente nel nuovo Pull Request, creando confusione per i tuoi colleghi.

Passo 1. Crea un branch per il nuovo task.

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

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

Nel nuovo branch crea il file CONTRIBUTING.md (dopo la creazione premi Add) e scrivi lì un messaggio agli altri sviluppatori. Dopo di che fai Commit and Push con un messaggio chiaro, per esempio: docs: Add contribution guide.

Questo è il passaggio chiave! Il Pull Request si crea sulla base di un branch che esiste già sul server remoto. Perciò, prima di creare il PR, devi inviare (push) il tuo nuovo branch su GitHub.

3. Creare un Pull Request da IntelliJ IDEA

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

Passo 1. Apri la scheda Pull Requests.

Nel lato sinistro della IDE c'è la scheda Pull Requests. Aprila e premi l'icona + per creare un nuovo PR.

Passo 2. Compila i dati per il PR.

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

1. Titolo: l'IDE spesso inserisce qui il nome del branch, ma è una pessima pratica. Il titolo deve essere breve, chiaro e riflettere l'essenza delle modifiche, come un buon messaggio di commit.
2. Descrizione: qui spieghi cosa e perché hai fatto.
3. Reviewers: qui scegli uno o più colleghi che devono controllare il tuo codice. Nel progetto didattico saltiamo questo passaggio, ma nel lavoro reale è obbligatorio.
4. Assignees: di solito indichi te stesso. Questo significa che sei l'autore e il principale responsabile del task e delle correzioni dopo il review.

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

4. Code review: controllo e discussione

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

Puoi vedere tutte le discussioni direttamente nella 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 un nuovo PR. Basta fare le modifiche necessarie nel codice nello stesso branch, fare un nuovo commit e inviarlo (push). Il Pull Request su GitHub si aggiornerà automaticamente aggiungendo i nuovi commit.

5. Completare il lavoro: merge e eliminazione del branch

Quando tutte le osservazioni sono state corrette e il team approva le tue modifiche, il Pull Request può essere unito. Di solito lo fa uno sviluppatore senior o tu stesso, se hai i permessi.

Passo 1. Merge

Il merge avviene più spesso sul sito di GitHub. Lì sotto il tuo PR apparirà un 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ù, ed è meglio eliminarlo per non sporcare il repository. GitHub proporrà automaticamente di farlo, mostrando il pulsante Delete branch.

Non dimenticare anche di cancellare la copia locale del branch nella tua IDE, per mantenere ordine. Si può fare dallo stesso menu di gestione dei branch.

6. Tre regole per il commit

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

Regola 1: scrivi messaggi chiari secondo uno standard

I tuoi commit sono messaggi che mandi al tuo team e a te stesso nel futuro. Una storia piena di messaggi "fix" o "update" è del tutto inutile. Lo standard più popolare si chiama Conventional Commits. Propone questa struttura:

<type>: <short description>

Type — è una parola corta che descrive la categoria delle tue modifiche:

• feat: (feature) — per nuove funzionalità.
• fix: — per la correzione di bug.
• docs: — per modifiche alla documentazione.
• style: — per correzioni di formattazione che non influenzano la logica del codice.
• refactor: — per cambiamenti nel codice che non aggiungono funzionalità né risolvono bug.
• test: — per aggiunta o 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 conseguenze se qualcosa va storto.

Ogni commit deve risolvere una sola task specifica.

• Male: un commit con messaggio "Update user page", che aggiunge il campo per l'avatar, corregge il bug 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 mirati sono molto più semplici da capire e gestire.

Regola 3: il commit non deve rompere il progetto

Ogni commit nel branch principale deve lasciare il progetto in uno stato funzionante. Prima di crearne uno dovresti almeno assicurarti che il codice compili. Ma come essere certi che non hai rotto qualcosa in un'altra parte del sistema? Affidarsi solo al controllo manuale è rischioso.

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

Come funziona?

Scrivi codice e test per esso. Poi configuri uno script speciale (workflow) direttamente su GitHub. Ora, non appena fai push nel tuo Pull Request, succede la magia:

1. GitHub Actions rileva l'evento e avvia il tuo script.
2. Compila automaticamente il progetto e esegue tutti i test.
3. Se tutti i test passano, 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. È proibito fare il merge di un PR del genere nel branch principale.

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

            subgraph Workflow
            C -- "Run" --> D[Run_tests]
            D --> E[Successo]
            D --> F[Fallimento]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[Developer]
            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 le notifiche. Se i test falliscono, GitHub Actions può inviare una mail a te o a tutto il team. Questo approccio crea una cultura dove i test non sono una formalità, ma una parte integrante dello sviluppo, e ognuno è responsabile della qualità del proprio codice.