3. Processo di sviluppo

Un progetto basato su git
Sviluppo in rami
Inviare richieste di pull
Ottenere l’accesso in scrittura a GIT

Come comune nei progetti open source, i contributi di codice e documentazione al progetto sono molto apprezzati. La comunità di QGIS è molto solidale. Questa sezione descrive la procedura per sviluppare e inserire i vostri contributi nel progetto QGIS.

3.1. Un progetto basato su git 

La complessità del codice sorgente di QGIS è aumentata considerevolmente negli ultimi anni. Quindi è difficile anticipare gli effetti collaterali che l’aggiunta di una funzionalità avrà. In passato, il progetto QGIS aveva cicli di rilascio molto lunghi perché richiedeva molto lavoro per ristabilire la stabilità del sistema software dopo l’aggiunta di nuove funzionalità. Per superare questi problemi, QGIS è passato ad un modello di sviluppo che utilizza il sistema di controllo di versione git: le nuove funzionalità sono codificate prima nei rami dei contributori e unite al master di QGIS (il ramo principale) quando sono finite e stabili.

Il codice sorgente di QGIS è ospitato su https://github.com/qgis/QGIS.

3.1.1. Ruoli 

Esistono vari ruoli su GitHub. Quando hai un account su GitHub sei già autorizzato a contribuire tramite un ramo del repository e hai il ruolo di “contributor”. Gli sviluppatori del nucleo sono «collaboratori» e possono fondere rami nel repository upstream e ufficiale.

3.1.2. Ambiente 

Per iniziare a usare e contribuire al repository di QGIS, devi:

avere un GitHub account
fare la tua copia del QGIS repository (vedere fork)
avere sul tuo sistema un git client installed
impostare il tuo git environment
e divertiti!

3.1.3. Installare git 

Il progetto git fornisce versioni recenti del software per la maggior parte delle piattaforme. Segui le istruzioni su https://git-scm.com/downloads per ottenere e installare la copia corrispondente al tuo sistema operativo e alla tua architettura. È anche possibile installare un client git GUI per sfogliare e gestire i tuoi repository (la maggior parte delle volte, installerà git se non è ancora disponibile).

3.2. Sviluppo in rami 

3.2.1. Contributi allo sviluppo 

Una volta iscritto su GitHub e avendo aperto un ramo del repository, puoi impegnarti come collaboratore.

Nota

I contributi al codice QGIS possono essere fatti dal tuo repository ramificato sul sito web GitHub. Il nuovo codice sarà automaticamente costruito dall’ambiente di test. Ma questo flusso di lavoro può rivelare rapidamente i suoi limiti quando si vogliono fornire modifiche complesse. Le istruzioni qui sotto presuppongono un clone locale.

Puoi contribuire avviando una richiesta di pull. Per farlo segui questi passi generici:

Clone your repository sul tuo computer locale e imposta l’ambiente di sviluppo
Crea un nuovo ramo e fai le modifiche per lo sviluppo
Esegui il commit delle modifiche e invia il ramo al fork remoto su GitHub. Una richiesta di pull viene offerta come link web (URL) subito dopo.
Apri una richiesta di pull (PR) chiedendo di estrarre i commit dal tuo ramo nel ramo master nel repository upstream.
Viene avviato un processo di revisione che informa gli altri contributori e collaboratori della richiesta di pull. Dovresti essere reattivi ai loro commenti e suggerimenti.

Nota

Un flusso di lavoro di Github più dettagliato è disponibile all’indirizzo https://reflectoring.io/github-fork-and-pull/.

Nota

La maggior parte dei progetti QGIS (sito web, documentazione, pyQGIS API, plugin…) sono disponibili nella pagina GitHub del progetto e possono ricevere contributi, seguendo lo stesso processo.

3.2.2. Accessing the Repository 

Per poter interagire dal disco locale sia con il fork remoto che con i repository upstream di QGIS, devi:

Fai un duplicato della tua copia sul tuo disco locale

cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

Collega il repository principale di QGIS (lo chiameremo upstream) al tuo
```
git remote add upstream https://github.com/qgis/QGIS.git
```

Controlla i repository remoti collegati

git remote -v
# origin   https://github.com/<YourName>/QGIS.git (fetch)
# origin   https://github.com/<YourName>/QGIS.git (push)
# upstream https://github.com/qgis/QGIS.git (fetch)
# upstream https://github.com/qgis/QGIS.git (push)

Il tuo repository online è ora accessibile dal disco locale e si può interagire con esso usando il nome origin. Ogni volta che vuoi recuperare le modifiche dal repository qgis/QGIS, usa upstream.

Nota

In QGIS manteniamo il codice più stabile nel ramo di rilascio corrente. Il ramo ``master”” contiene il codice per la cosiddetta serie di release “instabili”. Periodicamente si crea un ramo di release fuori da master, per poi continuare la stabilizzazione e l’incorporazione selettiva di nuove funzionalità in master.

Vedi il file INSTALL nell’albero dei sorgenti per istruzioni specifiche sulla creazione di versioni di sviluppo.

3.2.3. Procedura 

Annuncio iniziale su mailing list o issue repo:
Prima di iniziare, fai un annuncio sulla mailing list degli sviluppatori per vedere se un altro sviluppatore sta già lavorando alla stessa funzionalità. Puoi anche menzionare il tuo interesse come commento nella segnalazione del problema, se ne esiste una nel repo. Se la nuova funzionalità richiede modifiche all’architettura di QGIS, è necessaria una QGIS Enhancement Proposal (QEP).
Crea un ramo nel tuo repository locale:
Crea un nuovo ramo git per lo sviluppo della nuova funzionalità, basato sullo stato più recente del ramo master.
git fetch upstream master git checkout -b newfeature upstream/master
Ora puoi iniziare a sviluppare:
Codifica le modifiche nel disco locale con il tuo solito IDE. Ricordarti di scrivere una suite di test per le modifiche, quando appropriato.
Commit le tue modifiche nel repo git:
Quando effettui un commit, inserisci un commento descrittivo e fai piuttosto diversi piccoli commit se le modifiche in un certo numero di file non sono correlate. Al contrario, preferiamo raggruppare le modifiche correlate in un unico commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
A questo punto, potresti voler condividere il tuo lavoro con i membri della comunità di QGIS. Inserisci la tua nuova funzione nel tuo repository fork online:
```
git push origin newfeature
```
Nota

Se il ramo esiste già, le modifiche vengono inserite in esso, altrimenti viene creato.
Submit your changes con una richiesta di pull
Con l’apertura della richiesta di pull, viene attivata la suite di test automatici che verifica se le modifiche seguono le linee guida di codifica di QGIS e non interrompono alcuna funzionalità esistente. Devi risolvere eventuali problemi segnalati prima che il ramo venga incorporato nell“«upstream».

Suggerimento

Usiamo le azioni di GitHub per gestire i test da eseguire sul repository. Per comodità, puoi abilitare le azioni sul tuo repository, in modo che i test vengano eseguiti quando invii le modifiche. Puoi quindi aprire la richiesta di pull dopo che tutti i test sono stati superati, rendendo il processo di revisione più efficiente.
Effettuare regolarmente il rebase al master upstream:
Si consiglia di eseguire il rebase per incorporare le modifiche in master nel ramo su base regolare. In questo modo è più facile unire il ramo a master in un secondo momento. Dopo un rebase è necessario fare git push -f al tuo forked repo.
git pull --rebase upstream master git push -f origin newfeature

Nota

Vedi i seguenti siti per informazioni su come diventare un master GIT.

3.2.4. Test prima della fusione in master 

Quando hai completato la nuova funzionalità e sei soddisfatto della stabilità, fai un annuncio nella lista degli sviluppatori. Prima di unire il tutto, le modifiche saranno testate dagli sviluppatori e dagli utenti.

3.3. Inviare richieste di pull 

Ci sono alcune linee guida che ti aiuteranno a inserire facilmente le tue patch e le tue richieste di pull in QGIS e ci aiuteranno a gestire facilmente le patch che ci vengono inviate.

In generale è più facile per gli sviluppatori inviare richieste di pull su GitHub. Non descriviamo qui le richieste di pull, ma rimandiamo alla documentazione sulle richieste di pull di GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_.

Se fai una richiesta di pull, vi chiediamo di unire regolarmente il master al tuo ramo PR, in modo che il tuo PR sia sempre unificabile al ramo master upstream.

Se sei uno sviluppatore e vuoi valutare la coda delle richieste di pull, c’è un ottimo tool” che ti permette di farlo dalla linea di comando

In generale, quando invii una PR, ti devi assumere la responsabilità di seguirla fino al suo completamento: rispondi alle domande inviate da altri sviluppatori, cerca un «campione» per la tua funzionalità e ogni tanto ricordaglielo gentilmente se vedi che la tua PR non viene seguita. Tieni presente che il progetto QGIS è guidato da volontari e le persone potrebbero non essere in grado di occuparsi istantaneamente della tua PR. Analizziamo le richieste di pull in arrivo, ma a volte ci sfuggono delle cose. Non offendetevi o allarmatevi. Cercate di individuare uno sviluppatore che vi aiuti e contattatelo chiedendo se può esaminare la tua patch. Se ritieni che la PR non riceva l’attenzione che merita, puoi scegliere di accelerarla (in ordine di priorità):

Aiuta a rivedere le richieste di pull degli altri per liberare la persona assegnata alla tua.
Invia un messaggio alla mailing list per «pubblicizzare» la tua PR e per far capire quanto sarebbe bello includerla nel codice di base.
Invia un messaggio alla persona a cui è stata assegnata la PR nella coda PR.
Invia un messaggio a Marco Hugentobler (che gestisce la coda di PR).
Invia un messaggio al comitato direttivo del progetto chiedendo di contribuire all’inserimento della tua PR nel codice di base.

3.3.1. Le migliori modalità per creare una richiesta di pull 

Avvia sempre un ramo di feature dal master corrente.
Se stai codificando un ramo di funzionalità, non «unire» nulla in quel ramo, piuttosto rebase come descritto nel punto successivo per mantenere pulita la cronologia.
Prima di creare una richiesta di pull, fai git fetch upstream e git rebase upstream/master (dato che upstream è il remote per l’utente qgis e non il tuo remote, controlla il tuo .git/config o fai git remote -v | grep github.com/qgis).
Puoi fare ripetutamente un git rebase come nell’ultima linea senza fare alcun danno (purché l’unico scopo del tuo ramo è quello di essere unito a master).
Attenzione: Dopo un rebase devi fare git push -f al tuo forked repo. SVILUPPATORI DEL CORE: NON FATE QUESTO SUL REPOSITORY PUBBLICO DI QGIS!

3.3.2. Etichette speciali di notifica per i documentatori 

Esiste un’etichetta speciale (Needs Documentation) che può essere assegnata dai revisori alla tua richiesta di pull per generare automaticamente dei rapporti sui problemi nel repository QGIS-Documentation non appena la richiesta di pull viene aggiunta. Ricordati di indicare se la tua funzionalità merita tale etichetta.

Inoltre, puoi aggiungere tag speciali ai messaggi di commit per fornire maggiori informazioni ai documentatori. Il messaggio di commit viene quindi aggiunto al rapporto sul problema generato:

[needs-docs] per indicare a chi scrive i documenti di aggiungere documentazione supplementare dopo una correzione o un’aggiunta a una funzionalità già esistente.
[feature] in caso di nuove funzionalità. Inserire una buona descrizione nella PR è un buon inizio.

Gli sviluppatori sono pregati di usare queste etichette (senza distinzione tra maiuscole e minuscole), in modo che chi scrive i documenti abbia problemi su cui lavorare e una panoramica delle cose da fare. MA per favore prendetevi anche il tempo di aggiungere del testo: o nel commit O nella documentazione stessa.

3.3.3. La dovuta professionalità 

QGIS è rilasciato sotto licenza GPL. Devi fare il possibile per assicurarti di inviare solo patch che non siano gravate da diritti di proprietà intellettuale in conflitto. Inoltre, non inviare codice che non sei disposto a rendere disponibile sotto licenza GPL.

3.4. Ottenere l’accesso in scrittura a GIT 

L’accesso in scrittura all’albero dei sorgenti di QGIS è su invito. In genere, quando una persona invia diverse (non c’è un numero fisso) patch sostanziali che dimostrano una competenza e una comprensione di base del C++ e delle convenzioni di codifica di QGIS, uno dei membri del PSC o altri sviluppatori esistenti possono nominare quella persona al PSC per la concessione dell’accesso in scrittura. Il nominatore deve fornire un paragrafo promozionale di base sul motivo per cui ritiene che la persona in questione debba ottenere l’accesso in scrittura. In alcuni casi concederemo l’accesso in scrittura a sviluppatori non C++, ad esempio a traduttori e documentatori. In questi casi, la persona deve comunque dimostrare di essere in grado di inviare patch e, idealmente, deve aver inviato diverse patch sostanziali che dimostrino la sua comprensione della modifica della base del codice senza provocare malfunzionamenti, ecc.

Nota

Da quando siamo passati a GIT, è meno probabile che concediamo l’accesso in scrittura ai nuovi sviluppatori, poiché è semplice condividere il codice all’interno di github creando un fork di QGIS e inviando richieste di pull.

Controlla sempre che tutto sia compilato prima di fare qualsiasi commit/richiesta di pull. Cerca di essere consapevole dei possibili problemi che i tuoi commit possono causare a chi costruisce su altre piattaforme e con versioni vecchie o nuove delle librerie.