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.
I progetti su Github nascono per consentire la condivisione e la collaborazione, offrendo quindi ai programmatori che lo desiderano di contribuire alla realizzazione di incredibili progetti.
Rob Allen, contributor di Zend Framework ed autore del libro Zend Framework in Action, ha realizzato un ottimo promemoria per fornire una linea guida per principianti per contribuire ai progetti pubblicati su Github e quindi diventare a tutti gli effetti contributors!
Le linee guida sono basate sulle modalità di collaborazione di progetti come Zend Framework e Slim Framework…quindi bisogna sempre prima dare un’occhiata approfondita al README o al CONTRIBUTING file del progetto al quale si vuole contribuire!

Nell’esempio useremo Slim come progetto al quale contribuire, ed è necessaria almeno una conoscenza di base di Git.

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 Slim cliccare sul bottone fork.
Una volta creato vedremo il nuovo progetto, con sotto indicato il progetto dal quale abbiamo forkato (e cioè il progetto d’origine).

Github Fork

Adesso sarà necessario creare una copia locale, clonando dal progetto appena forkato al proprio computer.
Dalla nostra shell preferita sarà sufficiente digitare il seguente comando (il progetto verrà clonato dentro la cartella corrente):

N.B. Sarà possibile clonare via HTTPS o via SSH. Basterà selezionare l’indirizzo relativo dalla casella clone URL.

cloneUrl

Riceverete un output simile:

Accedete alla cartella del repository, ad esempio:

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 il comando:

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 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).

In alcuni progetti i branch sono nominati con il numero di versione (come nel caso di Slim), ed andremo a lavorare partendo dal branch di default.

Verifichiamo quindi di essere sul branch di partenza corretto:

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.

Infine creiamo il branch con il comando:

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.

N.B. Slim in questo momento è a cavallo tra due major release, quindi lo sviluppo di nuove feature sono consentite solo sulla nuova release.

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.

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:

Successivamente basterà andare su Github , e dal nostro fork cliccare sul bottone Compare & pull request.

newbranch

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.

pullrequest

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.
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.

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 e CONTRIBUTING 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…ringraziando il buon Allen speriamo  di essere stati utili!

Alla prossima

The following two tabs change content below.

Francesco Sciuti

Freelance a Vroom Agency
Amante dello sviluppo web, della grafica 3d e della buona musica (che non guasta mai!), 'web developpa' tutto il giorno...e prova a trovare sempre il bandolo della matassa in questo allegro ma sconfinato mondo.

//life motto
if(sad() === true) {
    sad().stop();
    beAwesome();
}