Contribuire a un repository open source

Completato

Dopo aver identificato un'area a cui è possibile contribuire, il passaggio successivo prevede la preparazione del contributo. In questa unità verrà illustrato come comunicare la propria intenzione di partecipare a un progetto, creare una richiesta pull e migliorare le possibilità che venga accettata.

Quando si tratta di contribuire a un progetto open source, la comunicazione è un fattore chiave per il successo. Si potrebbe provare disagio nel comunicare ad altri utenti le proprie proposte di modifiche o miglioramenti. Da questo dialogo nasceranno spesso discussioni e compromessi sull'idea originale.

Se non si comunica attivamente con gli altri utenti coinvolti in un progetto open source, si rischia di perdere tempo lavorando ad attività a cui sta già lavorando qualcun altro oppure di lavorare a funzionalità o miglioramenti che non sono in linea con i valori o le procedure consigliate del progetto. In entrambi i casi, sarà uno spreco di tempo per tutti. Al contrario, una comunicazione attiva garantisce che il proprio lavoro sia ben accolto e susciti interesse.

Come è possibile comunicare in modo efficiente con gli altri membri del progetto a proposito delle nuove funzionalità e modifiche? Prima di tutto mantenere una mentalità aperta, accettare il feedback e avere pazienza. I gestori dei progetti open source hanno probabilmente non solo un lavoro che li impegna durante il giorno, ma anche una vita privata. Se non si riceve immediatamente una risposta, attendere ancora un po' prima di contattare i gestori.

Comunicare la propria intenzione ai gestori

È sempre consigliabile iniziare comunicando la propria intenzione di collaborare, prima di dedicarsi effettivamente a un lavoro. Se non indicato diversamente nel file README, lo strumento di gestione dei problemi è in genere il più adatto a questo scopo.

• Se si vuole lavorare su un problema esistente, verificare che nessuno sia assegnato a esso esaminando la sezione Assegnatari . Controllare anche la sezione Richieste pull collegate . Se è presente una richiesta pull collegata significa che qualcuno vi sta già lavorando. Esaminare i commenti per verificare se qualcuno ha espresso interesse a lavorare al problema. Se è tutto chiaro, pubblicare un commento sul problema per indicare che si è interessati a occuparsene. In questo modo, chi dovesse subentrare in un secondo momento saprà che qualcuno sta lavorando al problema e, se necessario, i gestori possono rispondere fornendo indicazioni e consigli.

  

• Per lavorare a una nuova funzionalità o a un bug non ancora presente nello strumento di gestione dei problemi, creare un nuovo problema. Assicurarsi di seguire l'eventuale modello di problema proposto e di esprimere chiaramente la propria intenzione di lavorare al problema. Se si tratta della proposta di una nuova funzionalità o se il problema richiede molte modifiche, assicurarsi di ottenere l'approvazione dei gestori prima di procedere al passaggio successivo.

Creare una richiesta pull in un repository GitHub

Dopo aver comunicato l'intenzione di collaborare al progetto, è possibile iniziare a lavorare al contributo effettivo.

Il contributo avrà la forma di una richiesta pull o di un PR. Una richiesta pull è una particolare funzionalità di GitHub contenente alcuni elementi:

• Un titolo e una descrizione delle modifiche.
• Uno o più commit che costituiscono le modifiche proposte.
• Commenti, a cui tutti possono partecipare nell'ambito di una discussione sulle modifiche.
• Revisioni del codice, in cui è possibile trovare feedback dettagliato sulle modifiche ed eventualmente eseguire il commit dei suggerimenti.
• Controlli di stato provenienti, ad esempio, da test automatizzati che i gestori potrebbero aver implementato. I controlli di stato possono servire a scopi diversi. Ad esempio, possono assicurare che le modifiche seguano le regole del progetto o che non interrompano il codice.

Una volta creata, una richiesta pull può essere aggiornata con nuovi commit, commenti o revisioni del codice. Questo processo continua finché i gestori del progetto non approvano e uniscono la richiesta pull oppure rifiutano le modifiche e chiudono la richiesta pull. Il merge della richiesta pull implica che le modifiche sono state integrate nella codebase del progetto.

Creare una richiesta pull

1. Aprire la pagina GitHub del progetto a cui si vuole contribuire.

2. Selezionare il pulsante Fork per creare una copia del repository nell'account GitHub. Questo passaggio è necessario perché, per impostazione predefinita, non si è autorizzati ad apportare modifiche in un repository pubblico a meno che non si tratti della propria copia. Creando una copia del progetto tramite fork, si ottiene una copia dove è possibile apportare modifiche.

   

3. Selezionare Your repositories dal menu del profilo dell'account.

   

4. Selezionare il fork del repository.

5. Selezionare il pulsante Codice per ottenere informazioni su come "clonare" il repository Git nel computer locale.

   

6. Seleziona l'icona clipboard per copiare l'URL del repository, quindi inserisci in un terminale:

   git clone <REPOSITORY_URL>
   

   Questo comando creerà una copia del repository nel computer locale.

   In alternativa, è possibile usare GitHub Desktop se si preferisce usare un'applicazione. In alternativa, è possibile usare GitHub Codespaces se l'opzione viene proposta. GitHub Codespaces risulterà familiare agli utenti di Visual Studio Code.

7. Al termine della clonazione del progetto, immettere la cartella del progetto:

   cd <PROJECT_FOLDER>
   

8. (Facoltativo) Creare un nuovo ramo usando il comando seguente:

   git checkout -b <BRANCH_NAME>
   

   Questo passaggio non è obbligatorio, ma è fortemente consigliato. Con un nuovo ramo, è possibile lavorare separatamente a più contributi, ognuno dei quali usa un ramo diverso.

9. Apportare le modifiche richieste al progetto ed eseguirne il commit:

   git add .
   git commit -m "<COMMIT_MESSAGE>"
   

   Questi comandi prepareranno le modifiche per il commit, quindi creeranno un commit con il messaggio specificato. Assicurarsi di descrivere con precisione le modifiche nel messaggio di commit. È anche consigliabile verificare se nel file CONTRIBUTING sono menzionate convenzioni da seguire per i messaggi di commit.

10. Eseguire il push delle modifiche nel repository remoto usando il comando:

    git push --set-upstream origin <BRANCH_NAME>
    

    Questo comando crea un nuovo ramo nel repository upstream su GitHub (il fork), in cui esegue il push di tutti i commit.

    Nota

    Quando si parla di un repository upstream , si fa riferimento al repository remoto collegato al repository locale. origin è l'alias predefinito per l'URL del repository, creato da Git nel passaggio 4.

    Se in precedenza non si è creato un ramo, immettere solo git push.

11. Aprire il fork del progetto in GitHub e selezionare il pulsante Confronta e richiesta pull nella casella di suggerimento visualizzata.

    

12. Compila il titolo e la descrizione e seleziona Crea pull request.

    

    Se è disponibile un modello per la descrizione della richiesta pull, immettere tutte le informazioni obbligatorie. In caso contrario, assicurarsi di fornire un contesto sufficiente per permettere ai gestori di comprendere quali modifiche si stanno proponendo e perché. È anche consigliabile creare un collegamento al problema correlato indicandone il numero con #<ISSUE_NUMBER>. È possibile trovare il numero del problema accanto al titolo.

    

Superare i controlli di stato

Dopo aver creato la richiesta pull, potrebbe venire visualizzata una sezione con i controlli di stato nella parte inferiore, simile alla seguente:

Si tratta di controlli di stato automatizzati che i gestori hanno implementato per garantire una qualità coerente del progetto.

Per ottenere l'accettazione della richiesta pull, è necessario superare tutti i controlli automatizzati. Se uno ha esito negativo come nello screenshot precedente, selezionare il pulsante Dettagli per altre informazioni sull'errore e per scoprire cosa è necessario fare per risolverlo.

Se non si è certi di come procedere in caso di esito negativo di un controllo, è sempre possibile usare i commenti per chiedere ai gestori indicazioni o assistenza per risolvere il problema.

Chiedere indicazioni o revisioni per le richieste pull

Se non si è certi di alcune modifiche apportate e si vuole l'opinione dei gestori, la soluzione migliore è commentare direttamente le richieste pull. Se consideri le tue modifiche un lavoro in corso, hai anche la possibilità di creare una bozza di richiesta pull per chiedere indicazioni o assistenza da altri collaboratori.

Quando i gestori prendono in considerazione la richiesta pull, possono rispondere alla conversazione o esaminare direttamente le modifiche. La revisione di una richiesta pull può avere più esiti diversi:

• Le modifiche vengono approvate. Congratulazioni.
• La richiesta pull richiede alcune modifiche. Non è un problema. Esaminare attentamente il feedback ricevuto. Se si apportano le modifiche richieste, è probabile che la richiesta pull verrà accettata. Se si esegue il push di nuovi commit nel ramo, la richiesta pull verrà automaticamente aggiornata con le nuove modifiche.
• Il revisore ha inserito alcuni commenti. In genere significa che sono necessari altri dettagli sulle modifiche o sulla motivazione di tali modifiche.

Rispondere ai commenti sulla richiesta pull

Si ricordi di essere sempre rispettosi in tutte le comunicazioni e di seguire il codice di comportamento. Prima che le modifiche vengano accettate, è probabile che si svolga una discussione con i gestori o altri collaboratori.

Contribuire all'open source richiede pazienza. A volte non si ottiene un feedback immediato. Non contattare i gestori privatamente tramite posta elettronica, X o qualsiasi altro mezzo per ricevere una risposta più rapidamente. Questo comportamento è considerato irrispettoso. Una discussione pubblica offre anche ad altri collaboratori o utenti l'opportunità di conoscere il processo alla base delle modifiche e le procedure consigliate da seguire.