1. Una contribuzione passo dopo passo
Nota
Sebbene la documentazione QGIS sia utilizzata per illustrare il processo, tutti i comandi e i passaggi illustrati di seguito si applicano anche al sito Web QGIS.
Se stai leggendo queste righe è certamente perché sei disposto a contribuire a scrivere la documentazione di QGIS e stai cercando un modo per farlo. Sei venuti nel posto giusto, il presente documento ti guiderà attraverso i diversi modi per raggiungere questo obiettivo, mostrandoti i principali passi da seguire, i trucchi che puoi usare e le trappole a cui porre attenzione.
Per qualsiasi aiuto non esitare a chiedere postando un commento sul problema che stai 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 sei un contributore alle prime armi e non sai da dove cominciare, potresti essere interessato ad affrontare i nostri «rapporti di benvenuto» <https://github.com/qgis/QGIS-Documentation/contribute>`_.
Ci sono due modi principali, che non si escludono a vicenda, per modificare i file:
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 si ha ancora familiarità con git e con il vocabolario di GitHub, si consiglia di leggere il progetto GitHub Hello-world per imparare alcuni vocaboli e azioni di base che saranno usati 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.
Al termine, fai un breve commento sulle modifiche e cliccae su Proponi modifiche. 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:
Vai al tuo ramo di QGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation
)Clicca su e cerca il ramo
patch-xxx
. Seleziona questo ramo della patch. Il pulsante ora dirà Branch: patch-xxx`.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.
Per prima cosa, assicurati che il tuo ramo master
sia aggiornato con il ramo qgis:master
. Per fare ciò:
Vai alla pagina principale del tuo repository, ad esempio
https://github.com/<YourName>/QGIS-Documentation
. Il ramomaster
dovrebbe essere attivo con una indicazione se è aggiornato conqgis/QGIS-Documentation:master
o no.Se ha dei commit in precedenza rispetto al ramo upstream, è meglio usare il precedente shortcut button alternative finché non allinei il tuo ramo
master
.Se ha solo dei commit arretrati:
Espandi il menu a discesa Fetch Upstream sulla destra. Puoi
Compare i rami e vedi le nuove modifiche nel repository principale
Fetch and merge: trasferisce i cambiamenti dal ramo upstream al tuo.
Facciamo clic su Fetch and merge: dopo il processo, il tuo ramo viene indicato come aggiornato con
qgis/QGIS-Documentation:master
.
Clicca su nell’angolo in alto a sinistra del repository di QGIS-Documentation e inserisci un nome univoco nel campo di testo per creare un nuovo branch . Il nome del nuovo ramo dovrebbe essere correlato al problema che intendi risolvere. Il pulsante dovrebbe ora riportare Branch: branch_name.
Sei pronto a iniziare nuovi cambiamenti su di esso.
Attenzione
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.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.
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 ricevi un errore Permission denied (publickey) con il comando precedente, potrebbe esserci un problema con la chiave SSH. Vedere la guida di GitHub 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 prefissoFix
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 concorrenti, nella pagina della richiesta di pull su GitHub è disponibile un pulsante Resolve conflicts. Premere il pulsante e risolvere il problema come spiegato in Resolving a merge conflict on GitHub.
se il conflitto riguarda la ridenominazione o la rimozione di file, allora devi risolverlo usando le linee di comando di git. In genere, devi prima eseguire il rebase del tuo ramo sul ramo di destinazione usando la chiamata
git rebase targetBranch
e correggere i conflitti che vengono segnalati. Per saperne di più: Resolving a merge conflict using the command line
A volte, alla fine del processo di revisione, puoi ritrovarti con modifiche suddivise in più commit che non necessariamente sono validi. Le linee di comando di Git aiutano a ridurre questi commit a un numero minore e a messaggi di commit più significativi. Alcuni dettagli su Using git rebase on the command line