1. Una contribuzione passo dopo passo

Nota

Sebbene la documentazione QGIS sia utilizzata per dimostrare il processo, tutti i comandi e i passaggi illustrati di seguito si applicano anche al sito Web QGIS.

Se state leggendo queste righe è certamente perché siete disposti a contribuire a scrivere la documentazione di QGIS e state cercando un modo per farlo. Siete venuti nel posto giusto, il presente documento vi guiderà attraverso i diversi modi per raggiungere questo obiettivo, mostrandovi i principali passi da seguire, i trucchi che potete usare e le trappole a cui porre attenzione.

Per qualsiasi aiuto non esitate a chiedere postando un commento sul problema che state cercando di risolvere o scrivendo alla `lista QGIS-community-team <https://lists.osgeo.org/mailman/listinfo/qgis-community-team>``_. Maggiori dettagli su Partecipa alla documentazione.

Buttiamoci ora nel processo.

I sorgenti della documentazione sono memorizzati usando il sistema di controllo di versione git e sono disponibili su GitHub a https://github.com/qgis/QGIS-Documentation. Una lista di problemi da risolvere e di funzioni da spiegare può essere trovata su https://github.com/qgis/QGIS-Documentation/issues.

Suggerimento

Se è la prima volta che contribuisci e non sai da dove cominciare, potresti essere interessato ad analizzare i nostri welcoming reports.

Ci sono due modi principali, che non si escludono a vicenda, per modificare i file:

Using the GitHub web interface
Using Git command line tools.

1.1. Utilizzo dell’interfaccia web di GitHub 

L’interfaccia web di GitHub permette di fare quanto segue:

modifica file
vedere l’anteprima e fare il commit delle tue modifiche
effettuare una richiesta di pull per l’inserimento delle modifiche nel repository principale
creare, aggiornare o eliminare rami

Se non hai ancora familiarità con git e il vocabolario di GitHub, potresti voler leggere il progetto GitHub Hello-world per imparare alcuni vocaboli e azioni di base che verranno utilizzati di seguito.

Nota

Se stai risolvendo un problema segnalato

Se stai facendo delle modifiche per risolvere un issue, aggiungi un commento al report del problema per assegnarlo a te stesso. Questo impedirà a più di una persona di lavorare sullo stesso problema.

1.1.1. Segnala QGIS-Documentation 

Supponendo che tu abbia già un account GitHub <https://github.com/join>`_, devi prima fare una duplicazione dei file sorgente della documentazione.

Naviga alla pagina QGIS-Documentation repository e clicca sul pulsante in alto a destra.

Nel tuo account GitHub troverai un repository QGIS-Documentation (https://github.com/1/QGIS-Documentation). Questo repository è una copia del repository ufficiale di QGIS-Documentation dove hai pieno accesso in scrittura e puoi fare modifiche senza influenzare la documentazione ufficiale.

1.1.2. Apportare modifiche 

Ci sono diversi modi per contribuire alla documentazione di QGIS. Li mostriamo separatamente qui sotto, ma puoi passare da un processo all’altro senza alcun problema.

Alternativa 1: usa la scorciatoia `Modifica su GitHub`

Le pagine sul sito web della documentazione di QGIS possono essere modificate rapidamente e facilmente cliccando sul link Modifica su GitHub in alto a destra di ogni pagina.

Questo aprirà il file nel ramo qgis:master con un messaggio in cima alla pagina che ti dice che non hai accesso in scrittura a questo repo e le tue modifiche saranno applicate a un nuovo ramo del tuo repository.
Fai le tue modifiche. Poiché la documentazione è scritta usando la sintassi reStructureText, a seconda delle tue modifiche, potresti aver bisogno di fare riferimento alle writing guidelines 1.
Quando hai finito, fai un breve commento sulle tue modifiche e clicca su Propose changes. Questo genererà un nuovo branch (patch-xxx) nel tuo repository.
Dopo aver cliccato su Propose changes, github passerà alla pagina Comparing changes.
- Se hai finito di apportare modifiche, passa a Compare changes nella sezione Share your changes via Pull Request qui sotto.
- Se ci sono ulteriori modifiche che vuoi fare prima di inviarle a QGIS, segui questi passi:
  1. Vai al tuo ramo di QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation)
  2. Clicca su e cerca il ramo patch-xxx. Seleziona questo ramo della patch. Il pulsante ora dirà Branch: patch-xxx`.
  3. Vai a Modify files qui sotto.

Nota

La scorciatoia Edit on GitHub è anche disponibile nel menu a discesa in fondo alla barra laterale sinistra.

Alternativa 2: creare un ramo ad hoc nel tuo repository di documentazione 

Puoi modificare i file direttamente dal tuo ramo della Documentazione QGIS.

Clicca su nell’angolo in alto a sinistra del tuo repository QGIS- Documentation e inserisci un nome univoco nel campo di testo per creare un nuovo branch . Il nome del nuovo ramo dovrebbe riferirsi al problema che intendi risolvere. Il pulsante dovrebbe ora indicare Branch: branch_name`.

Suggerimento

Fai le tue modifiche in un ramo ad hoc, mai nel **branch master.

Per convenzione, evita di fare cambiamenti nel tuo ramo master tranne quando unisci le modifiche dal ramo master di qgis/QGIS-Documentation nella tua copia del repository QGIS-Documentation. I rami separati ti permettono di lavorare su più problemi allo stesso tempo senza interferire con altri rami. Se fai un errore puoi sempre cancellare un ramo e ricominciare creandone uno nuovo dal ramo master.

1.1.3. Modificare file 

Sfoglia i file sorgente del tuo ramo della QGIS-Documentation fino al file che deve essere modificato
Fai le tue modifiche seguendo le writing guidelines
Quando hai finito, vai al riquadro Commit Changes in fondo alla pagina, fai un breve commento sulle tue modifiche e clicca su Commit Changes per impegnare le modifiche direttamente nel tuo ramo. Assicurati che Commit directly to the branch_name branch. sia selezionato.
Ripeti i passi precedenti per qualsiasi altro file che deve essere aggiornato per correggere il problema

1.1.4. Condividi le tue modifiche via Pull Request 

Devi fare una richiesta di pull per integrare le tue modifiche nella documentazione ufficiale.

Nota

Se hai usato una Modifica su GitHub link

Dopo aver fatto il commit delle tue modifiche GitHub aprirà automaticamente una nuova pagina confrontando le modifiche che hai fatto nel tuo ramo patch-xxx con il ramo master qgis/QGIS-Documentation.

Passa a Step 2 qui sotto.

Inizia una nuova richiesta di pull 

Vai alla pagina principale del repository QGIS-Documentation e clicca su New pull request.

Confronta le modifiche 

Se vedi due finestre di dialogo, una che dice base:master e l’altra compare:branch_name (vedi figura), questo fonderà solo le tue modifiche da uno dei tuoi rami al tuo ramo master. Per risolvere questo problema clicca sul link compare across forks.

../../_images/githubCompareAcrossForks.png — Fig. 1.1 Se la tua pagina Comparing changes assomiglia a questa, clicca sul link compare across forks.

Dovresti vedere quattro menu a tendina. Questi ti permetteranno di confrontare i cambiamenti che hai fatto nel tuo ramo con il ramo master in cui vuoi fonderti. Essi sono:

base fork: il ramo in cui vuoi fondere le tue modifiche
base: il ramo della diramazione di base in cui vuoi fondere le tue modifiche
head fork: il ramo che ha modifiche che si vogliono incorporare nel ramo base
compare: il ramo con tali modifiche

Seleziona qgis/QGIS-Documentation come ramo base con master come base, imposta la diramazione principale al tuo repository <YourName>/QGIS-Documentation, e imposta compare al tuo ramo modificato.

../../_images/githubCreatePullRequestComparison.png — Fig. 1.2 Comparare le modifiche tra `qgis/QGIS-Documentation` e il tuo repository

Una spunta verde con le parole Able to merge mostra che le tue modifiche possono essere unite alla documentazione ufficiale senza conflitti.

Clicca sul pulsante Create pull request.

Avvertimento

Se vedi

Questo significa che ci sono dei conflicts. I file che stai modificando non sono aggiornati con il ramo a cui stai puntando perché qualcun altro ha fatto un commit che va in conflitto con le tue modifiche. Puoi ancora creare la richiesta di pull ma dovrai sistemare qualsiasi conflicts per completare la fusione.

Suggerimento

Sebbene sia stata tradotta, la latest version della documentazione di QGIS è ancora mantenuta e i problemi esistenti sono risolti. Se stai correggendo problemi per una release diversa, cambia base da master al ramo appropriato release_... nei passi di cui sopra.

Descrivi la tua richiesta di pull 

Si aprirà una casella di testo: inserisci qualsiasi commento pertinente al problema che stai affrontando.

Se questo si riferisce ad un particolare`issue <https://github.com/qgis/QGIS-Documentation/issues>`_, aggiungi il numero del problema ai tuoi commenti. Questo viene fatto inserendo # e il numero del problema (e.g. #1234). Se preceduto da termini come fix o close, il problema in questione verrà chiuso non appena la richiesta di pull verrà inserita.

Aggiungi i link alle pagine di documentazione che stai cambiando.

Clicca su Create pull request.

Rivedere e commentare la richiesta di pull 

Come visto sopra, chiunque può inviare modifiche alla documentazione attraverso le richieste di pull. Allo stesso modo chiunque può rivedere le richieste di pull con domande e comments. Può essere che lo stile di scrittura non corrisponda alle linee guida del progetto, che la modifica manchi di alcuni dettagli importanti o di screenshot, o che tutto sia perfetto e in ordine. La revisione aiuta a migliorare la qualità del contributo, sia nella forma che nella sostanza.

Per rivedere una richiesta di pull:

Vai alla pagina delle richieste di pull <https://github.com/qgis/QGIS-Documentation/pulls>`_ e clicca sulla richiesta di pull su cui vuoi fare un commento.
In fondo alla pagina troverai una casella di testo dove puoi lasciare commenti generali sulla richiesta di pull.
Per aggiungere commenti su linee specifiche,
1. Clicca su e trova il file che vuoi commentare. Potresti dover cliccare su Display the source diff per vedere le modifiche.
2. Scorri fino alla linea che vuoi commentare e clicca su . Questo aprirà una casella di testo che ti permetterà di lasciare un commento.

Commenti specifici sulla linea possono essere pubblicati:

come commenti singoli, usando il pulsante Add single comment. Vengono pubblicati man mano. Usalo solo se hai pochi commenti da aggiungere o quando replichi su un altro commento.
o come parte di una revisione, premendo il pulsante Start a review. I tuoi commenti non vengono inviati automaticamente dopo la validazione, permettendoti di modificarli o cancellarli in seguito, di aggiungere un riassunto dei punti principali della revisione o istruzioni globali riguardanti la richiesta di pull e se la approvi o meno. Questo è il modo più conveniente poiché è più flessibile e ti permette di strutturare la tua revisione, modificare i commenti, pubblicare quando sei pronto e inviare una singola notifica ai fruitori del repository e non una notifica per ogni commento. Ottieni more details.

../../_images/githubAddLineComment.png — Fig. 1.3 Commentare una linea con un suggerimento di modifica

I commenti di riga possono incorporare suggerimenti che l’autore della richiesta di pull può applicare alla richiesta di pull. Per aggiungere un suggerimento, fai clic sul pulsante ^{Insert a suggestion} in cima alla casella di testo del commento e modifica il testo all’interno del blocco del suggerimento.

Suggerimento

Proferire il commit di suggerimenti alla tua richiesta di pull come un batch

Come autore di una richiesta di pull, quando incorpori direttamente il feedback dei revisori nella tua richiesta di pull, evita di usare il pulsante Commit suggestion in fondo al commento quando hai molti suggerimenti da affrontare e preferisci aggiungerli come un batch commit, cioè:

Passa alla scheda
Premi Add suggestion to batch per ogni riformulazione che vuoi includere. Vedrai un contatore che aumenta man mano che vai avanti.
Premi uno qualsiasi dei pulsanti Commit suggestions quando sei pronto ad applicare i suggerimenti alla tua richiesta di pull, e inserisci un messaggio che descriva le modifiche.

Questo aggiungerà tutte le modifiche al tuo ramo come un singolo commit, risultando in una storia più leggibile dei cambiamenti e meno notifiche per i fruitori del repository. Per inciso, procedere in questo modo ti farà anche risparmiare molti clic.

Apportare correzioni 

Una nuova richiesta di pull verrà automaticamente aggiunta alla lista delle richieste di pull <https://github.com/qgis/QGIS-Documentation/pulls>`_. Altri redattori e amministratori esamineranno la tua richiesta di pull e potranno dare suggerimenti o chiedere correzioni.

Una richiesta di pull innescherà anche controlli automatici di compilazione (ad esempio, per la formattazione rst, sintassi del codice python), e i report sono visualizzati in fondo alla pagina. Se viene trovato un errore, una croce rossa apparirà accanto al tuo commit. Clicca sulla croce rossa o su Details nella sezione di riepilogo in fondo alla pagina della richiesta di pull per vedere i dettagli dell’errore. Dovrai correggere qualsiasi errore o avvertimento segnalato prima che le tue modifiche siano inviate al repository qgis/QGIS-Documentation.

Puoi fare modifiche alla tua richiesta di pull fino a quando non viene unita al repository principale, sia per migliorare la tua richiesta, sia per indirizzare le modifiche richieste, sia per correggere un errore di compilazione.

Per apportare modifiche clicca sulla scheda nella tua pagina di richiesta di pull e clicca sul pulsante matita accanto al nome del file che vuoi modificare.

Qualsiasi modifica aggiuntiva sarà automaticamente aggiunta alla tua richiesta di pull se fai queste modifiche allo stesso ramo che hai presentato nella tua richiesta di pull. Per questo motivo, dovresti apportare modifiche aggiuntive solo se tali modifiche si riferiscono al problema che intendi risolvere con quella richiesta di pull.

Se vuoi risolvere un altro problema, crea un nuovo ramo per quelle modifiche e ripeti i passi di cui sopra.

Un amministratore inserirà il tuo contributo dopo che ogni errore di compilazione è stato corretto e dopo che tu e gli amministratori siete soddisfatti delle tue modifiche.

1.1.5. Eliminare il tuo ramo di fusione 

Puoi eliminare il ramo dopo che le tue modifiche sono state incorporate. Cancellare i vecchi rami ti evita di avere rami inutilizzati e superati nel tuo repository.

Naviga al tuo ramo del repository QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation).
Clicca sulla scheda Branches. Sotto Your branches vedrai una lista dei tuoi rami.
Clicca sull’icona ^{Delete this branch} per cancellare qualsiasi ramo indesiderato.

1.2. Usare gli strumenti a riga di comando di Git 

L’interfaccia web di GitHub è un modo semplice per aggiornare il repo della documentazione di QGIS con i tuoi contributi, ma non offre strumenti per:

raggruppare i tuoi commit e pulire la tua cronologia delle modifiche
correggere possibili conflitti con il repo principale
costruire la documentazione per testare le tue modifiche

Hai bisogno di install git sul tuo disco rigido per avere accesso a strumenti più avanzati e potenti e avere una copia locale del repository. Alcune nozioni di base di cui potresti avere spesso bisogno sono esposte qui sotto. Troverai anche delle regole a cui badare anche se opti per l’interfaccia web.

Negli esempi di codice qui sotto, le linee che iniziano con $ mostrano i comandi che dovresti digitare, mentre # sono commenti.

1.2.1. Repository locale 

Ora sei pronto per ottenere un clone locale del tuo repository QGIS-Documentation.

Puoi copiare il tuo repository QGIS usando l’URL web come segue:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

La prima linea di comando è semplicemente un esempio. Dovresti adattare sia il percorso che l’URL del repository, sostituendo <YourName> con il tuo nome utente github.

Verifica quanto segue:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

origin è il nome del repository remoto del tuo repository QGIS-Documentation.
master è il ramo principale di default. Non dovresti mai usarlo per contribuire! **Mai!

In alternativa puoi clonare il tuo repository QGIS usando il protocollo SSH:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git

Suggerimento

Errore di autorizzazione negata (chiave pubblica)?

Se ottieni un errore Permission denied (publickey) con il primo comando, potrebbe esserci un problema con la tua chiave SSH. Vedi GitHub help per i dettagli.

Verifica quanto segue se hai usato il protocollo SSH:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

Puoi iniziare a lavorare qui ma nel processo a lungo termine avrai un sacco di problemi quando spingerai il tuo contributo (chiamato Pull Request nel processo di github) come il ramo principale del repository qgis/QGIS-Documentation divergerà dal tuo repository locale/remoto. Devi quindi tenere traccia del repository remoto principale e lavorare con i rami.

1.2.2. Aggiungere un altro repository remoto 

Per poter seguire il lavoro nel progetto principale, aggiungi un nuovo repository remoto nel tuo repository locale. Questo nuovo repository remoto è il repository QGIS-Documentation del progetto QGIS:

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

Allo stesso modo, puoi usare il protocollo SSH per aggiungere un repository remoto nel tuo repository locale:

$ git remote add upstream [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream        [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream        [email protected]:qgis/QGIS-Documentation.git (push)

Così ora hai la scelta tra due repository remoti:

origin per effettuare il push del tuo ramo locale nel tuo repository remoto
upstream per fondere (se hai il diritto di farlo) il tuo contributo a quello ufficiale O per aggiornare il tuo ramo master del repository locale dal ramo master del repository ufficiale.

Nota

upstream è solo un’etichetta, una specie di nome standard ma puoi chiamarlo come vuoi.

1.2.3. Aggiornare il tuo ramo base 

Prima di lavorare su un nuovo contributo, dovresti sempre aggiornare il ramo master nel tuo repository locale. Supponendo che tu sia disposto ad inviare le modifiche alla documentazione di test, esegui le seguenti linee di comando:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository (aka <YourName>/QGIS-Documentation)
$ git push origin master

Ora hai i tuoi repository locali e remoti che hanno entrambi il loro ramo master aggiornato con il ramo ufficiale master di QGIS-Documentation. Puoi iniziare a lavorare sul tuo contributo.

Nota

Cambia il ramo se vuoi contribuire al doc rilasciato

Insieme alla documentazione di test, continuiamo a correggere i problemi nella latest release, il che significa che puoi anche contribuire ad essa. Segui il codice di esempio della sezione precedente, sostituendo master con il ramo corrispondente dell’ultima documentazione.

1.2.4. Contribuire al tuo ramo di produzione 

Ora che il tuo ramo base è aggiornato, devi creare un ramo dedicato in cui aggiungere tuoi contributi. Lavora sempre su un ramo diverso da quello di base! Sempre!

# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

Poche parole sui comandi commit/push:

cercare di fare un solo commit (cambiamento atomico), cioè affrontare un solo problema
cerca di spiegare attentamente cosa cambi nel titolo del tuo commit e nella descrizione. La prima riga è un titolo e dovrebbe iniziare con una lettera maiuscola e avere una lunghezza di 80 caratteri, non finire con un .. Sii conciso. La tua descrizione può essere più lunga, termina con un . e puoi dare molti più dettagli.
usa un # con un numero per riferirti ad un problema. Usa il prefisso Fix se correggi il ticket: il tuo commit chiuderà il ticket.

Ora che le tue modifiche sono salvate e modificate nel tuo ramo locale, hai bisogno di inviarle al tuo repository remoto per creare una richiesta di pull:

$ git push origin myNewBranch

1.2.6. Pulire il tuo repository locale e remoto 

Dopo che la tua PR è stata fusa nella documentazione ufficiale di QGIS, puoi cancellare il tuo ramo. Se lavori molto in questo modo, in poche settimane avrai un sacco di rami inutili. Quindi mantieni il tuo repository pulito in questo modo:

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

E non dimenticare di aggiornare il ramo principale nella tua repository locale!

1.3. Ulteriori letture 

Oltre all’interfaccia web di Github e agli strumenti a riga di comando git esposti sopra, ci sono anche applicazioni GUI che puoi usare per creare e gestire i tuoi contributi alla documentazione.

Quando i cambiamenti nella richiesta di pull sono in conflitto con i recenti cambiamenti inseriti nel ramo di destinazione, i conflitti devono essere risolti prima che una fusione sia possibile:
- se il conflitto riguarda poche linee corrispondenti, un pulsante Resolve conflicts è disponibile nella pagina della richiesta di pull su Github. Premi il pulsante e risolvi il problema come spiegato su https://help.github.com/articles/resolving-a-merge-conflict-on-github/
- se il conflitto coinvolge la rinominazione o la rimozione di file, allora avresti bisogno di risolvere il conflitto usando le linee di comando git. Tipicamente, devi prima fare il rebase del tuo ramo sul ramo di destinazione usando la chiamata git rebase targetBranch e correggere i conflitti che vengono riportati. Leggi di più su https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
A volte, alla fine del processo di correzione, puoi finire con cambiamenti divisi in più commit che non sono necessariamente utili. Le linee di comando di Git ti aiutano a comprimere questi commit in un numero più piccolo e in messaggi di commit più significativi. Alcuni dettagli su https://help.github.com/articles/using-git-rebase-on-the-command-line/