3. Processo di sviluppo

Un progetto basato su git
Sviluppo in rami
Inviare richieste di pull
Obtaining GIT Write Access

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 (vedi 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
Create a new branch and do the edits for development
Commit your changes and push your branch back to the remote fork on GitHub. A pull request is then offered as web link (URL) right after.
Open a pull request (PR) asking to pull the commit(s) from your branch into the master branch into the upstream repository.
A review process is being started informing other contributors and collaborators about your pull request. You should be reactive to their comments and suggestions.

Nota

A more detailed Github’s Fork & Pull Workflow is available at 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 

To be able to interact from your local disk with both your remote fork and the QGIS upstream repositories, you need to:

Fai un duplicato della tua copia sul tuo disco locale

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

Connect the QGIS main repository (we will name it upstream) to yours
```
git remote add upstream https://github.com/qgis/QGIS.git
```

Check connected remote repositories

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)

Your online repository is now accessible from your local drive and you can interact with it using the name origin. Whenever you’d like to fetch changes from the qgis/QGIS repository, use upstream.

Nota

In QGIS we keep our most stable code in the current release branch. master branch contains code for the so called “unstable” release series. Periodically we will branch a release off master, and then continue stabilisation and selective incorporation of new features into master.

See the INSTALL file in the source tree for specific instructions on building development versions.

3.2.3. Procedura 

Initial announcement on mailing list or issues repo:
Before starting, make an announcement on the developer mailing list to see if another developer is already working on the same feature. You can also mention your interest as a comment in the issue report if one exists in the repo. If the new feature requires any changes to the QGIS architecture, a QGIS Enhancement Proposal (QEP) is needed.
Create a branch in your local repository:
Create a new git branch for the development of the new feature, based on latest state of the master branch.
git fetch upstream master git checkout -b newfeature upstream/master
Now you can start developing:
Code your changes in your local disk with your usual IDE. Remember to write tests suite for your modifications, when appropriate.
Commit your changes to the git repo:
When making a commit, put a descriptive comment and rather do several small commits if the changes across a number of files are unrelated. Conversely we prefer you to group related changes into a single commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
Now, you may want to share your work with QGIS community members. Push your new feature up to your online fork repository by doing:
```
git push origin newfeature
```
Nota

If the branch already exists, your changes will be pushed into it, otherwise, it is created.
Submit your changes con una richiesta di pull
With opening the pull-request, the automated test suite is triggered and checks whether your changes follow the coding guidelines of QGIS and do not break any existing feature. You’d need to fix any reported issues before your branch is merged upstream.

Suggerimento

We use GitHub actions to manage the tests to be run on the repository. For convenience, you can enable the actions on your repository so that the tests are run when you push the changes. You’d then open the pull request after they all passed, making the review process more efficient.
Rebase to upstream master regularly:
It is recommended to rebase to incorporate the changes in master to the branch on a regular basis. This makes it easier to merge the branch back to master later. After a rebase you need to git push -f to your forked repo.
git pull --rebase upstream master git push -f origin newfeature

Nota

See the following sites for information on becoming a GIT master.

3.2.4. Testing before merging back to master 

When you are finished with the new feature and happy with the stability, make an announcement on the developer list. Before merging back, the changes will be tested by developers and users.

3.3. Inviare richieste di pull 

There are a few guidelines that will help you to get your patches and pull requests into QGIS easily, and help us deal with the patches that are sent to use easily.

In general it is easier for developers if you submit GitHub pull requests. We do not describe Pull Requests here, but rather refer you to the GitHub pull request documentation.

If you make a pull request we ask that you please merge master to your PR branch regularly so that your PR is always mergeable to the upstream master branch.

If you are a developer and wish to evaluate the pull request queue, there is a very nice tool that lets you do this from the command line

In general when you submit a PR you should take the responsibility to follow it through to completion - respond to queries posted by other developers, seek out a “champion” for your feature and give them a gentle reminder occasionally if you see that your PR is not being acted on. Please bear in mind that the QGIS project is driven by volunteer effort and people may not be able to attend to your PR instantaneously. We do scan the incoming pull requests but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you and contact them asking them if they can look at your patch. If you feel the PR is not receiving the attention it deserves your options to accelerate it should be (in order of priority):

Help review others pull requests to free the person assigned to yours.
Send a message to the mailing list “marketing” your PR and how wonderful it will be to have it included in the code base.
Send a message to the person your PR has been assigned to in the PR queue.
Invia un messaggio a Marco Hugentobler (che gestisce la coda di PR).
Send a message to the project steering committee asking them to help see your PR incorporated into the code base.

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

Always start a feature branch from current master.
If you are coding a feature branch, don’t «merge» anything into that branch, rather rebase as described in the next point to keep your history clean.
Before you create a pull request do git fetch upstream and git rebase upstream/master (given upstream is the remote for qgis user and not your own remote, check your .git/config or do git remote -v | grep github.com/qgis).
You may do a git rebase like in the last line repeatedly without doing any damage (as long as the only purpose of your branch is to get merged into master).
Attention: After a rebase you need to git push -f to your forked repo. CORE DEVS: DO NOT DO THIS ON THE QGIS PUBLIC REPOSITORY!

3.3.2. Special labels to notify documentors 

There is a special label (Needs Documentation) that can be assigned by reviewers to your pull request to automatically generate issue reports in QGIS-Documentation repository as soon as your pull request is merged. Remember to mention whether your feature deserves such a label.

Moreover, you can add special tags to your commit messages to provide more information to documenters. The commit message is then added to the generated issue report:

[needs-docs] to instruct doc writers to please add some extra documentation after a fix or addition to an already existing functionality.
[feature] in case of new functionality. Filling a good description in your PR will be a good start.

Please devs use these labels (case insensitive) so doc writers have issues to work on and have an overview of things to do. BUT please also take time to add some text: either in the commit OR in the docs itself.

3.3.3. Due Diligence 

QGIS is licensed under the GPL. You should make every effort to ensure you only submit patches which are unencumbered by conflicting intellectual property rights. Also do not submit code that you are not happy to have made available under the GPL.

3.4. Obtaining GIT Write Access 

Write access to QGIS source tree is by invitation. Typically when a person submits several (there is no fixed number here) substantial patches that demonstrate basic competence and understanding of C++ and QGIS coding conventions, one of the PSC members or other existing developers can nominate that person to the PSC for granting of write access. The nominator should give a basic promotional paragraph of why they think that person should gain write access. In some cases we will grant write access to non C++ developers e.g. for translators and documentors. In these cases, the person should still have demonstrated ability to submit patches and should ideally have submitted several substantial patches that demonstrate their understanding of modifying the code base without breaking things, etc.

Nota

Since moving to GIT, we are less likely to grant write access to new developers since it is trivial to share code within github by forking QGIS and then issuing pull requests.

Always check that everything compiles before making any commits / pull requests. Try to be aware of possible breakages your commits may cause for people building on other platforms and with older / newer versions of libraries.