Come contribuire

Questa guida fornisce un'esercitazione passo-passo su come contribuire al codice sorgente e alle traduzioni di Gambas.

Riguarda l'organizzazione del codice, alcune linee guida che contribuiscono a comprendere come usare Git e GitLab per inviare il tuo contributo.

Come usare Git e GitLab

Il codice sorgente di Gambas è gestito da un repository Git, ospitato su GitLab.com.

Per gestire nuovi contributi, utilizziamo il Flusso di lavoro del fork del progetto : poiché i contributori non hanno il permesso di scrivere direttamente sul codice sorgente di Gambas, dovrai creare un repository separato contenente le tue modifiche, quindi creare una richiesta di unione (merge request) chiedendo agli sviluppatori di Gambas di unire (merge) le tue modifiche al repository principale.

Sebbene ciò possa sembrare complesso per i nuovi collaboratori, questo documento è stato creato per guidare questo processo, passo dopo passo.

Se hai problemi con i passaggi menzionati qui, o se hai qualche domanda riguardo un contributo, puoi chiedere sulla mailing list.

Come creare un account GitLab

Innanzitutto, è necessario un account GitLab per inviare qualunque modifica.

Ti consigliamo anche di usare SSH per lavorare con i repository Git, anziché HTTPS. Non solo non dovrai inserire il nome utente e la password di GitLab ogni volta che desideri interagire con il repository, ma è anche più sicuro poiché la password non viene mai inviata attraverso la rete.

Puoi anche usare GPG per firmare i tuoi commit, sebbene non sia necessario.

Fare il Fork del Repository Gambas

Ora che il tuo account GitLab è configurato, possiamo fare il fork del repository Gambas. Questo creerà una copia del repository Gambas, ma sarà di tua proprietà, quindi potrai apportare qualsiasi modifica tu voglia.

Per fare questo, basta andare alla pagina del progetto Gambas e fare clic sul pulsante "Fork".

Ti verrà quindi chiesto dove posizionare il fork del repository. Una volta completato, il nuovo repository apparirà sotto il tuo account.

Adesso puoi clonare il repository sul tuo computer locale, usando il seguente comando (sostituisci <yourusername> con il tuo username GitLab): 

git clone [email protected]:<yourusername>/gambas.git

Apportare modifiche al tuo repository

Una volta completata la clonazione, è possibile apportare modifiche alla propria copia locale, che dovrà quindi essere consegnata (con il comando git commit) e inviata (git push).

Innanzitutto, puoi controllare quali file sono stati modificati con il comando git status. È sempre bene controllare prima di fare il commit!

Puoi anche vedere le differenze complete con il comando git diff.

Una volta fatto tutto, dovrai selezionare quali file vuoi successivamente consegnare usando il comando git add.

Puoi selezionare file o directory specifici usando git add file1.c file2.c main/gbx, o semplicemente selezionare tutto usando git add -A.

È quindi possibile effettuare il commit usando il comando git commit. Questo comando aprirà un editor per consentire di scrivere il messaggio di commit.

Per alcune linee guida su come scrivere i messaggi di commit, consultare la sezione Scrivere messaggi di commit.

Questo comando avvierà l'editor predefinito (di solito vi), ma puoi cambiarlo impostando la variabile d'ambiente EDITOR sul comando che avvia il tuo editor preferito.

Ora che il commit è fatto, puoi inviarlo al tuo repository GitLab usando il comando git push.

Creazione della merge request (richiesta di unione)

Con le modifiche ora trasferite al repository GitLab, il passaggio finale è quello di creare una Merge Request, chiedendo gentilmente agli sviluppatori di Gambas per unire le modifiche al repository principale di Gambas.

Poiché questo processo è interamente realizzato tramite GitLab, utilizzare le seguenti istruzioni per creare le merge request.

È probabile che le tue modifiche non vengano accettate immediatamente e ti verrà chiesto dai manutentori di Gambas di apportare alcune modifiche.

In questo caso, è possibile apportare le modifiche, consegnarle (commit) e quindi inviarle (push). La richiesta di unione (merge request) su GitLab verrà aggiornata automaticamente, non dovrai ricrearla.

Mantieni aggiornato il tuo repository

Durante il tempo in cui apporti modifiche alla tua versione del codice sorgente di Gambas, o mentre la tua richiesta viene esaminata, è probabile che il repository Gambas riceva alcuni aggiornamenti.

Poiché un repository ottenuto da un fork è sostanzialmente un clone, la versione ufficiale e la tua versione sono completamente separate e non riceverà automaticamente nuovi commit.

Tuttavia, puoi configurare il tuo repository locale in modo che si colleghi a entrambi i repository, in modo da poter estrarre le modifiche dal repository ufficiale di Gambas, unirle con le tue modifiche localmente e quindi inviarle al tuo repository.

Innanzitutto, occorre configurare il tuo repository Git locale aggiungendo il repository Gambas originale come secondo remoto: 

git remote add upstream https://gitlab.com/gambas/gambas.git

Ora abbiamo aggiunto un nuovo remoto chiamato upstream al repository locale, indicando il repository Gambas originale. (Puoi elencare tutti i remoti con il comando git remote -v).

Questo significa che Git ora può estrarre le modifiche dal repository Gambas originale usando il comando seguente: 

git pull upstream master

Questo comando prenderà le modifiche dal ramo master del remoto upstream.

Se hai eseguito dei commit alla tua versione del repository, li unirà con le nuove modifiche, creando un nuovo commit di unione.

Quando l'unione è completa, puoi semplicemente usare git push per inviare tutte queste modifiche alla tua versione del repository. Se hai qualche richiesta di unione in sospeso, verranno aggiornate automaticamente.

Scrivere messaggi di commit

Al fine di generare automaticamente i log delle modifiche per ogni versione, i commit nel repository Gambas devono seguire un formato molto specifico.

Ecco un esempio: 

This commit contains things, adds stuff and has lots of fluff (Questo commit contiene delle cose, sono state aggiunte altre cose e contiene molta fuffa).
(ma questo non andrà nel changelog)

[GB.QT4]
* NEW: Added things to the component (Aggiunte cose al componente).
* BUG: Fixed a bug in the Foo function (Risolto un bug nella funzione Foo).
* NEW: Added this very long modification... (Aggiunta questa modifica molto lunga...)
  ...and it takes more than one Line To Write it (...e ci vuole più di una riga per descriverla).

This won't go into the changelog either (...).

[COMPILER]
* BUG: What an awful bug!
* OPT: Make things go faster.

[GB.GTK3]
* NEW: The component is now complete!

Secondo la convenzione per i messaggi di commit di Git, la prima riga di ogni commit è una breve descrizione di ciò che contiene. Questa riga non finisce nel changelog, ma appare nei log di git e nell'interfaccia di GitLab.

Quindi, il messaggio di commit è composto dalle seguenti parti:

  • Uno slot, tra parentesi quadre (ad es. [GB.QT4])

  • Una o più modifiche, ognuna preceduta da un tag, che può essere * NEW: , * BUG: o * OPT: , con uno spazio alla fine.

Il nome dello slot è quello del componente modificato (in maiuscolo) o uno di questi se le modifiche non influiscono su un componente:
  • [INTERPRETER] per i cambiamenti nell'interprete (gbx3).

  • [COMPILER] per le modifiche nel compilatore (gbc3).

  • [ARCHIVER] per modifiche nell'archiviatore (gba3).

  • [INFORMER] per modifiche nell'informatore (gbi3)

  • [DEVELOPMENT ENVIRONMENT] per modifiche nell'IDE (gambas3).

  • [CONFIGURATION] per modifiche nel processo di configurazione di automake/autoconf

  • [WIKI CGI SCRIPT] per modifiche negli script CGI della wiki.

  • [WEB SITE MAKER] per modifiche nel generatore del sito Web Gambas.

  • [EXAMPLES] per modifiche negli esempi.

Il nome del tag è uno dei seguenti:

  • NEW è per nuove funzionalità o traduzioni, aggiornamenti o altri miglioramenti;

  • BUG è per la correzione di errori o altre correzioni

  • OPT è per ottimizzazioni

Le cose senza impatto per l'utente (come refactoring o pulizia del codice) non dovrebbero finire nel log delle modifiche.

Tutte le righe senza tag non verranno visualizzate nel registro delle modifiche, ma se si desidera che una modifica si estenda su più righe, sarà necessario farla precedere da due spazi.