Fork, pull request, collaborazione open source

Quando non hai permesso di pushare direttamente su un repository, lavori tramite fork. Il fork è una copia remota sotto il tuo account. Tu pushi lì, poi apri una pull request verso il repository originale.

È il workflow base dell’open source, ma torna utile anche in aziende con permessi separati.

Perché questa lezione conta

Contribuire a un progetto che non possiedi richiede attenzione: devi tenere il fork aggiornato, creare branch piccoli, rispettare linee guida e proporre PR facili da revieware.

Una buona PR non è solo codice corretto. È una modifica spiegata, limitata, testata e allineata al progetto.

Obiettivo operativo

Alla fine della lezione devi saper configurare origin e upstream, creare branch da upstream aggiornato, pushare sul fork e aprire PR pulite.

Setup fork-based

git clone git@github.com:tu/progetto.git
cd progetto
git remote add upstream git@github.com:org/progetto.git
git remote -v

Struttura:

origin   -> tuo fork
upstream -> repo originale

Aggiornare:

git fetch upstream
git switch main
git rebase upstream/main
git push origin main

Se preferisci non riscrivere main del fork, puoi fare merge. La cosa importante è sapere quale scelta fai.

Branch per contributo

Non lavorare direttamente su main del fork. Crea branch:

git switch -c fix/typo-readme upstream/main

Così il branch parte dalla base aggiornata del progetto originale.

Poi:

git push -u origin fix/typo-readme

Apri PR da tu:fix/typo-readme verso org:main.

PR piccola

Una PR open source efficace ha:

1. scope stretto;
2. titolo chiaro;
3. descrizione del problema;
4. soluzione proposta;
5. test eseguiti;
6. screenshot se UI;
7. link a issue se esiste;
8. nessun refactor laterale.

Se vuoi correggere typo e refactorare architettura, apri due PR.

Tenere aggiornata una PR

Se upstream cambia:

git fetch upstream
git switch fix/typo-readme
git rebase upstream/main
git push --force-with-lease

Force-with-lease è accettabile sul tuo branch del fork. Se il progetto preferisce merge commit, segui la guida di contributing.

Leggere le regole del progetto

Prima di contribuire:

1. CONTRIBUTING.md;
2. issue template;
3. stile commit;
4. test richiesti;
5. licenza;
6. codice di condotta;
7. branch target.

Molte PR vengono rallentate perché ignorano istruzioni già scritte.

Gestire feedback di review

Quando arriva feedback, evita di mescolare tutto in un unico commit confuso. Se il progetto preferisce storia pulita, puoi fare commit temporanei durante la review e poi squashare o rebaseare prima del merge. Se invece il progetto mantiene i commit, ogni correzione deve restare leggibile.

Rispondi ai commenti indicando cosa hai cambiato e dove. Una buona collaborazione open source è anche asincrona: il maintainer deve capire lo stato della PR senza ricostruire tutto dal diff.

Laboratorio guidato

Usa un tuo repo sandbox come se fosse open source:

1. crea repo originale;
2. crea fork simulato o secondo clone;
3. configura origin e upstream;
4. crea branch da upstream;
5. fai modifica minima;
6. push su origin;
7. scrivi descrizione PR completa.

Non serve disturbare un progetto reale per imparare il flusso.

Output atteso

Un playbook fork:

clone fork
add upstream
fetch upstream
branch da upstream/main
commit piccolo
push origin branch
PR con descrizione e test
rebase su upstream se richiesto

Errori comuni

Lavorare su main del fork. Rende difficile gestire più PR.

PR troppo grande. Riduce probabilità di review rapida.

Non leggere CONTRIBUTING. Porta a cicli inutili.

Dimenticare upstream. Il fork resta indietro e le PR divergono.

Checklist di verifica

• so distinguere origin e upstream;
• creo branch da upstream aggiornato;
• push sul mio fork;
• PR ha scope e test chiari;
• so aggiornare la PR con rebase e force-with-lease.

Collegamenti

• Modulo: Collaborazione con remoti — lezione 25 del corso.
• Il modulo 6 applica questi concetti ai workflow di team.