Importante
La traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 95.16%.
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 esitate a chiedere in un commento sulla segnalazione del problema che state cercando di risolvere o a scrivere alla lista QGIS-community-team. Leggete le informazioni generali sul supporto della comunità QGIS.
Buttiamoci ora nel processo.
Documentation sources are stored using the Git version control system and are available on GitHub at https://github.com/qgis/QGIS-Documentation. A list of issues to fix and features to explain can be found at 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
If you are not yet familiar with Git and GitHub vocabulary, you may want to read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.
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 hai già un GitHub account, devi prima fare il fork dei file sorgenti 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/<YourName>/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 della documentazione del sito web QGIS possono essere modificate rapidamente e facilmente cliccando sul link “Modifica su GitHub”:
in alto a destra di ogni pagina,
oppure nel menu a tendina nella parte inferiore della barra laterale sinistra.
Questo aprirà il file nel ramo
qgis:mastercon 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.Nota
If you do have write access to the QGIS repository, no message is displayed and your changes will likely be saved directly in the main repository instead of your fork. However, to keep the repository clean, it is recommended that even contributors with write access work from their forks when editing documentation.
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.
Una volta terminate le modifiche al file, premi Commit changes… e aggiungi un breve titolo che spieghi le modifiche apportate. Se necessario, puoi anche fornire una spiegazione più dettagliata.
Premi Proponi modifiche, salvando le modifiche nel tuo repository. Questo genererà un branch (
patch-xxx) dedicato nel tuo repository e il browser web aprirà la pagina Confronto modifiche.Se il problema che stai affrontando non richiede ulteriori modifiche, passa alla 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)Selezionalo. Il pulsante
ora visualizzerà Branch: patch-xxx.Passa alla sezione Modify files qui sotto.
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 l’upstream, ad esempio il ramo “qgis/QGIS-Documentation:master”. Per farlo:
Vai alla pagina principale del tuo repository, ad esempio
https://github.com/<YourName>/QGIS-Documentation. Il ramomasterdovrebbe essere attivo con una indicazione se è aggiornato conqgis/QGIS-Documentation:mastero 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 Sincronizza fork sulla destra. Puoi:
Confronta i rami e visualizza le nuove modifiche nel ramo upstream che non sono ancora presenti tra le tue.
Fetch and merge: importa le modifiche dal ramo upstream nelle tue.
Clicca su Fetch and merge: al termine del processo, il tuo ramo sarà contrassegnato come aggiornato con
qgis/QGIS-Documentation:master.
Clicca su
nell’angolo in alto a sinistra del tuo repository forked QGIS-Documentation e inserisci un nome univoco nel campo di testo per creare un nuovo branch. Si consiglia di scegliere un nome per il nuovo ramo che sia correlato al problema che intendi risolvere. Ciò renderà più facile identificare il ramo in un secondo momento.Premi Crea ramo <branch_name> dal master. Il pulsante
dovrebbe ora visualizzare branch_name.Sei pronto per apportare nuove modifiche al tuo nuovo ramo.
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
Assicurati che il ramo che desideri modificare sia attivo: il suo nome è visualizzato nel menu in alto a sinistra o nell’URL della pagina.
Sfoglia i file sorgente fino a trovare il file che deve essere modificato.
Aggiorna il testo seguendo le writing guidelines
Una volta terminate le modifiche al file, premi Commit changes… e aggiungi un breve titolo che spieghi le modifiche apportate. Se necessario, puoi anche fornire una spiegazione più dettagliata.
Assicurati che sia selezionata l’opzione Commit direttamente sul ramo <branch_name>.
Premi Commit changes per salvare le modifiche nel ramo.
Per aggiornare o aggiungere un nuovo file immagine:
Sfoglia il tuo ramo fino alla cartella del file da aggiornare o aggiungere.
In alto a destra, utilizza il menu per selezionare e caricare i file dal tuo disco rigido. Puoi trovare suggerimenti su come formattare un’immagine per la documentazione alla pagina gestione_screenshot.
Se esiste già un file con lo stesso nome, questo verrà sovrascritto.
Esegui nuovamente il commit delle modifiche sul ramo di destinazione.
Ripeti i passaggi precedenti per tutti gli altri file che devono essere aggiornati per risolvere 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
You need to install Git on your hard drive in order to get access to more advanced and powerful tools and have a local copy of the repository. Some basics you may often need are exposed below. You’ll also find rules to care about even if you opt for the web interface.
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
The former command line is simply an example.
You should adapt both the path and the repository URL, replacing <YourName>
with your GitHub user name.
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
You can start to work here but in the long term process you will get a lot of issues when you will push your contribution (called Pull Request in GitHub process) as the master branch of the qgis/QGIS-Documentation repository will diverge from your local/remote repository. You then need to keep track of the main remote repository and work with branches.
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 prefissoFixse 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. Altre letture
Other than the GitHub web interface and the Git command line tools exposed above, there are also GUI applications you can use to create and manage your contributions to the documentation.
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.
if the conflict involves files renaming or removal, then you’d need to resolve the conflict using Git command lines. Typically, you have to first rebase your branch over the target branch using
git rebase targetBranchcall and fix the conflicts that are reported. Read more at 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





