Github è uno degli strumenti più noti e diffusi per lo sviluppo collaborativo di software. Il suo core è basato su Git, uno strumento che permette di effetture il controllo di versione del codice, rendendo agevole lo sviluppo collaborativo.
Per poter partecipare allo sviluppo di un nuovo progetto è necessario:
- ottenere una copia locale del progetto originale
- creare un “canale” di comunicazione con il progetto originale per poter recuperare gli aggiornamenti degli altri dev
- utilizzare un meccanismo per sottoporre le nostre modifiche agli sviluppatori originali che le integreranno dopo approvazione (pull request)
Nel corso di questo post vedremo come effettuare il setup dell’ambiente di lavoro per poter partecipare allo sviluppo in un progetto.
I passi per contribuire ad un progetto esistente sono piuttosto semplici, e possono essere applicati anche su altri repository basati su Git. Ovviamente, prima di proseguire è necessario avere un proprio account su GitHub.
Il primo step è la creazione di una copia del repository originale sul proprio repository Github: per fare questo è necessario creare un fork del progetto originale. Dalla pagina del progetto cliccare il pulsante fork in alto a destra.
Una volta forkato, il progetto comparirà all’interno dell’elenco dei nostri progetti (con l’indicazione del progetto originale).
A questo punto si possono intraprendere le normali attività di sviluppo: per prima cosa procedere con la clonazione del progetto “forkato” in locale, prendendo l’indirizzo direttamente all’interno del pulsante “Clone or download”:
Questa operazione può essere effettuata tramite un IDE anche se, personalmente preferisco effettuarlo direttamente a linea di comando:
$> git clone https://[URL_GIT_PROGETTO]
Al termine il risultato sarà quello di avere una cartella locale contenente tutto il codice del progetto. A questo punto siamo finalmente pronti per lo sviluppo.
I passi che abbiamo fatto, quindi, sono stati:
- fork del progetto originale sul nostro repository
- clonazione del progetto “forkato” sul nostro ambiente locale
Quello che manca è ancora un “meccanismo” che consenta di legare il nostro repository a quello remoto, in modo da poter intercettare nuovi aggiornamenti sul repository originale e trasferirli sul nostro. Questo riferimento viene chiamato upstream.
L’idea è quella di creare due canali separati: uno verso il nostro repository, con al possibilità di leggere e scrivere, e uno verso il repository originale dal quale possiamo solo leggere (e scaricare gli aggiornamenti degli altri dev).
Per creare quest’ultimo riferimento dobbiamo partire dall’indirizzo Git del progetto originale (attenzione quello originale!) che troviamo all’interno del pulsante “Clone Download”. Dopo esserci posizionati all’interno della cartella locale, è necessario utilizzare il seguente comando:
$> git remote add upstream https://URL_PROGETTO_ORIGINALE_GIT
E’ stato cosi creato il riferimento al progetto orginale. In Git quindi ci troveremo due riferimenti:
- origin: che punta al nostro progetto forkato (permessi lettura e scrittura)
- upstream: che punta al repository originale (solo lettura)
A questo punto abbiamo raggiunto il nostro obiettivo. I comandi per effettuare l’aggiornamento dei nostri branch sono:
Aggiornamento del progetto locale a partire da quello originale:
$> git pull upstream master
ed il corrispondente aggiornamento del nostro branch locale:
$> git push origin master
Una nota particolare riguarda il nome del branch master che è stato rinominato recentemente in main.
Il setup del nostro ambiente locale è terminato. Si può iniziare con lo sviluppo vero e proprio, utilizzando tutte le logiche e funzionalità dei branch.
Terminato lo sviluppo, si rende necessario integrare il codice con quello del progetto originale. Questa operazione in git viene effettuata il meccanismo delle pull request:
- viene inviata la richiesta allo sviluppatore del progetto originale
- lo sviluppatore “originale” verifica il codice
- la richiesta può essere accettata, quindi il codice viene inglobato all’interno del progetto
- la richiesta può essere rifiutata, eventualmente con una serie di indicazione e commenti
Creazione di una pull request
La pull request viene generata a partire dal nostro repository forkato (l’unico contentente le nostre modifiche). Le pull request possono essere effettuate solo attraverso il portale di github. Una volta aperto il nostro progetto, è possibile effettuare il submit della request utilizzando il pulsante:
che permette di accedere alla form per la request.
Nel campo descrizione si è soliti indicare in maniera dettagliata il tipo di integrazione/sviluppo che è stato implementato.
Una volta inviata la pull request non rimane che aspettare il feedback da parte degli sviluppatori e rispondere alle loro eventuali richieste/commenti.