Github: guida per principianti per contribuire ad un progetto
Qualunque programmatore al giorno d’oggi sarà arrivato, navigando, almeno una volta su Github, il servizio web di hosting per lo sviluppo di progetti software, che usa il sistema di controllo di versione Git.
(Se doveste essere tra quelli che non ci sono mai capitati vi prego di contattarmi data la rarità dell’evento! :D)
I progetti su Github nascono con lo scopo di consentire la condivisione e la collaborazione, offrendo quindi ai programmatori che lo desiderano di contribuire alla realizzazione di incredibili progetti.
Online è possibile trovare ottimi promemoria per fornire linee guida per principianti per contribuire ai progetti pubblicati su Github e quindi diventare a tutti gli effetti contributors!
Comunemente per contribuire ad un progetto si parte sempre da una semplice buona pratica…bisogna sempre prima dare un’occhiata approfondita al README o al CONTRIBUTING file del progetto al quale si vuole contribuire!
Nell’esempio useremo Redis Patterns Console come progetto al quale contribuire, ed è necessaria almeno una conoscenza di base di Git.
Redis Patterns Console è una console online interattiva (e reattiva) per provare e studiare Redis (il database in-memory più famoso al mondo!) ed i suoi più comuni pattern, il tutto direttamente da una web application e quindi senza dover installare e configurare nulla!
Clonare una copia del progetto sul tuo computer
Come prima cosa è necessario creare una copia del progetto (e quindi del repository) sul proprio account Github.
Per farlo è sufficiente accedere alla pagina Github del progetto al quale si desidera contribuire (in questo caso quella di Redis Patterns Console) e cliccare sul bottone fork (posizionato in alto a destra accanto ai bottoni Watch e Stars).
Una volta creato vedremo il nuovo progetto, con sotto indicato il progetto dal quale abbiamo forkato (e cioè il progetto d’origine).
Adesso sarà necessario creare una copia locale sul computer, clonando dal progetto appena forkato al proprio computer.
Dalla nostra shell preferita sarà sufficiente digitare il seguente comando di clone del repo, indicando il percorso corretto che troverete cliccando sul bottone Clone or download:
N.B. il progetto verrà clonato dentro la cartella corrente in una sottocartella con il nome del progetto.
Ad esempio nel mio caso quindi digiterò:
git clone https://github.com/fsciuti/redis-patterns-console.git
N.B. Sarà possibile clonare via HTTPS o via SSH. Basterà selezionare l’indirizzo relativo dalla casella clone URL.
Il risultato dovrebbe essere (tendenzialmente) questo:
Accedete alla cartella del repository, ad esempio:
cd redis-patterns-console
Infine sarà necessario aggiungere un nuovo riferimento ad un repository remoto (che viene denominato remote da Git), in modo da puntare al progetto originale, così da poter “catturare” eventuali cambiamenti fatti dalla comunità e trasferirli sul proprio repository locale.
L’indirizzo in questo caso lo preleviamo ancora una volta dalla casella clone URL, ma questa volta dal progetto d’origine dal quale abbiamo forkato,
Per creare un remote (che chiameremo upstream) ci basterà eseguire, nel nostro caso, il comando:
git remote add upstream https://github.com/acadevmy/redis-patterns-console
A questo punto avremo due remote, e precisamente:
- origin che corrisponde al fork del progetto sul nostro profilo Github, ed al quale avremo un accesso in lettura/scrittura;
- upstream che corrisponde al progetto principale, e dal quale potremo solo leggere.
Fare qualcosa…magari di utile!
Ecco la parte divertente…contribuire.
Normalmente si inizia facendo qualche bugfix, spulciando la issue tracker del progetto.
A volte nei progetti è utilizzata la label Easy Pick (o delle varianti della stessa) per identificare le issue che possono essere assegnate a chiunque.
Lavorare con i Branch
La prima regola è che ogni parte di lavoro ha il suo branch!
Se il progetto segue il git-flow, saranno presenti sia il branch master che develop. In caso di bugs si creerà il branch partendo da master, per nuove features invece da develop.
Nel caso sia presente solo master si creerà partendo da master stesso (ma và? :D).
N.B. In alcuni progetti i branch sono nominati con il numero di versione, ed andremo a lavorare partendo dal branch di default.
Verifichiamo quindi di essere sul branch di partenza corretto:
git checkout develop
Una volta certi di essere nel branch corretto, sincronizziamo il progetto locale prelevando il codice aggiornato dal repository upstream (quindi il progetto d’origine), e sincronizziamo il repository origin (quindi il nostro fork) con il progetto locale.
git pull upstream master && git push origin master
Infine creiamo il branch con il comando:
git checkout -b hotfix/myfix
N.B. Nei progetti che seguono git-flow i nomi dei branch hanno i prefissi hotfix/ o feature/ a seconda di ciò che si sta andando a realizzare.
Andiamo a questo punto a realizzare il nostro lavoro (per bene mi raccomando), badando a lavorare solo una singola nuova funzionalità o soluzione di bug (non divaghiamo risolvendo 100 bugs diversi contemporaneamente!), ed utilizzando dei commenti ben pensati e formattati.
Spesso i progetti sono corredati da suite di test ed è necessario realizzare i test per ciò che si è scritto, prima di ritenere il proprio lavoro completo. Ovviamente fate si che i test passino eh! :D
N.B. Redis Patterns Console è stato appena pubblicato e quindi è possibile che non siano ancora presenti delle issues da correggere…ma di sicuro bugs ce ne saranno eh! :D
Creare la Pull Request
Una volta aver fatto (per bene mi raccomando ancora!) il vostro lavoro sarà il momento di mandarlo per passarlo alla revisione dei maintainers del progetto originale!
Per farlo dovremo inviare una Pull Request dal nostro repository forkato al repository del progetto originale, iniziando dal sincronizzare il remote origin.
git push -u origin hotfix/myfix
L’output dovrebbe essere simile a:
Questo comando creerà il branch hotfix/myfix sul remote origin (e quindi sul nostro fork), e grazie al parametro -u non ci sarà necessità successivamente di indicare nuovamente il branch e quindi, successivamente, potremo utilizzare semplicemente il comando:
git push origin
Successivamente basterà andare su Github , e dal nostro fork cliccare sul bottone Compare & pull request.
Nel caso in cui sarà presente il seguente box, sarà fondamentale che lo leggiate (anche se lo dovreste aver fatto già prima), perché contiene le informazioni necessarie per contribuire al progetto.
Verificare che il base fork punti correttamente al repository d’origine e che il branch sia corretto.
Indicare un breve (ma significativo) titolo e completare il tutto con una adeguata descrizione (normalmente nel file CONTRIBUTING.md del progetto troverete delle indicazioni a riguardo, come ad esempio la necessità di indicare il numero della issues nella Pull Request, etc..).
Effettuate un doppio controllo sul diff dei cambiamenti che apporterete con questa Pull Request, verificando che realmente ci sia tutto ciò che avete previsto e che sia corretto…e finalmente…fare un click su Create Pull Request per inviare tutto in revisione.
N.B. Delle linee guida molto interessanti e comunemente utilizzate per la redazione dei commits la potete trovare al link sottostante:
https://www.conventionalcommits.org/en/v1.0.0/
Verifica da parte dei Maintainers
Prima che il vostro lavoro sia integrato nel progetto sarà abbondantemente revisionato da parte dei revisori che valuteranno il lavoro svolto, e se ritenuto valido si occuperanno del merge (o vi invieranno dei feedback di code review). Se tutto quindi andrà bene potrete quindi ritenervi un valido contributor!
Riepilogo degli steps
Possiamo riassumere le il tutto nei seguenti steps:
- Fork del progetto Github e clonazione in locale del fork stesso;
- Creazione di un remote (upstream) per sincronizzare il repository locale con quello d’origine;
- Creare un branch di lavoro;
- Lavorare sul codice fino alla follia (leggendo prima il README.md e CONTRIBUTING.md file);
- Sincronizzare il repository del nostro fork (origin) con il lavoro svolto in locale;
- Creare una nuova Pull Request su Github;
- Rispondere ad eventuali feedback di code review.
Più o meno dovrebbe essere tutto…speriamo di essere stati utili, e non dimenticate di darci una mano con il Redis Patterns Console!
Un ringraziamento particolare a Salvo Pappalardo per la revisione dell’articolo. :)
