3. Development Process

As common in open source projects, contributions of code and documentation to the project are highly appreciated. The QGIS community is very supportive. This section describes the procedure for developing and merging your contributions in the QGIS project.

3.1. A git based project 

The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very long release cycles because it was a lot of work to reestablish the stability of the software system after new features were added. To overcome these problems, QGIS switched to a development model using the git version control system: new features are coded in the contributor branches first and merged to the QGIS master (the main branch) when they are finished and stable.

QGIS source code is hosted at https://github.com/qgis/QGIS.

3.1.1. Roles 

There exist various roles on GitHub. When having an account on GitHub you are already allowed to contribute by forking the repository and have the role «contributor». Core developers are «collaborators» and can merge branches into the upstream and official repository.

3.1.2. Environment 

To get started using and contributing to the QGIS repository, you need to:

have a GitHub account
make your own copy of the QGIS repository (see fork)
have a git client installed on your system
set up your git environment
and have fun!

3.1.3. Installing git 

The git project provides recent versions of the software for most platforms. Follow the instructions at https://git-scm.com/downloads to get and install the copy corresponding to your OS and architecture. There, it’s also possible to install a git GUI client to browse and manage your repositories (most of the time, it will install git if not yet available).

3.2. Dezvoltarea în ramuri 

3.2.1. Contributions to development 

Once signed up on GitHub and having forked the repository, you can engage as a contributor.

Notă

Contributions to QGIS code can be done from your forked repository on the GitHub website. The new code will automatically be built by the test environment. But this workflow can quickly reveal its limits when you want to provide complex changes. Instructions below will assume a local clone.

You can contribute by initiating a pull request. To do that follow these generic steps:

Clone your repository onto your local computer and set up the build environment
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.

Notă

A more detailed Github’s Fork & Pull Workflow is available at https://reflectoring.io/github-fork-and-pull/

Notă

Most of the QGIS projects (website, documentation, pyQGIS API, plugins…) are available in the project GitHub page and can get contributions, following the same process.

3.2.2. Accesarea Depozitului 

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

Make a clone of your copy on your local disk

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.

Notă

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
```
Notă

If the branch already exists, your changes will be pushed into it, otherwise, it is created.
Submit your changes with a pull-request
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.

Sfat

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

Notă

Parcurgeți următoarele site-uri pentru informații despre cum putți deveni un maestru GIT.

3.2.4. Efectuarea de teste înaintea fuzionării cu ramura master 

Când ați terminat cu noua caracteristică și vă mulțumește stabilitatea, faceți un anunț pe lista dezvoltatorilor. Înainte de fuziunea cu masterul, modificările vor fi testate de către dezvoltatori și utilizatori.

3.3. Submitting Pull Requests 

Iată câteva indicații care vă vor ajuta să obțineți cu ușurință corecții și solicitări de actualizare pentru proiectele QGIS, facilitându-ne gestionarea corecțiilor.

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.
Trimiterea unui mesaj în lista de discuții, pentru a «populariza» PR-ul, indicând și cât de bine ar fi dacă ar fi inclus în baza de cod.
Trimiterea unui mesaj persoanei din lista de PR-uri, căreia i-a fost asignată cererea dvs.
Trimiterea unui mesaj comitetului director al proiectului, cerându-le să vă ajute la încorporarea PR-ului în codul de bază.

3.3.1. Cele mai bune practici pentru crearea unei cereri de actualizare 

Creați întotdeauna o ramură pentru o funcționalitate, pornind de la ramura master curentă.
Atunci când codificați ramura pentru o caracteristică, nu „îmbinați” nimic cu acea ramură, ci mai degrabă folosiți comanda rebase, așa cum este descris în punctul următor, pentru a păstra curat istoricul.
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).
Ați putea executa comanda Git rebase, în mod repetat, fără a provoca nici un prejudiciu (atât timp cât singurul scop al ramificării dvs. este de a obține fuzionarea cu ramura master).
Atenție: După rebase trebuie să efectuați git push -f` în depozitul ramificat. DEZVOLTATORI DE BAZĂ: NU FACEȚI ASTA ÎNTR-UN DEPOZIT QGIS PUBLIC!

3.3.2. Etichete speciale pentru a notifica documentatorii 

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] pentru a aminti creatorilor documentației să ceară adăugarea de informații suplimentare, după corectarea sau îmbunătățirea unei funcționalități existente deja.
[feature] in case of new functionality. Filling a good description in your PR will be a good start.

Rugăm dezvoltatorii să folosească aceste etichete (nu se face diferenţiere între litere mari şi mici), astfel încât creatorii documentației să identifice problemele pe care le au și să aibă o privire de ansamblu asupra lucrurilor de făcut. DAR, faceți-vă, de asemenea, timp pentru a adăuga un text: fie în commit, fie chiar în documentație.

3.3.3. Măsuri de Protecţie 

QGIS este licențiat sub GPL. Ar trebui să depuneți toate eforturile pentru a vă asigura că trimiteți numai corecții care nu sunt grevate de drepturi de proprietate intelectuală, de natură conflictuală. De asemenea, nu trimiteți un cod care nu se încadrează în GPL.

3.4. Obținerea Accesului de Scriere în GIT 

Accesul de scriere în arborele sursei QGIS are loc pe bază de invitație. În mod obișnuit, atunci când o persoană depune mai multe corecții substanțiale (nu există un număr fix), care să demonstreze competența și înțelegerea C++ de bază și a convențiilor de codificare QGIS, unul dintre membrii PSC, sau alți dezvoltatori, pot nominaliza persoana respectivă la acordarea accesului la scriere. Cel care face nominalizarea ar trebui să justifice printr-un paragraf promoțional, motivele pentru care consideră că o persoană ar trebui să aibă acces la scriere. În unele cazuri, vom acorda acces la scriere dezvoltatorilor non C++, de ex. pentru traducători și creatorii de documentație. Chiar și în aceste cazuri, persoanele trebuie să demonstreze o înțelegere a proceselor de modificare a bazei de cod fără producerea de erori, etc.

Notă

Din momentul orientării către GIT, suntem mai puțin susceptibili la acordarea accesului de scriere pentru noii dezvoltatori, deoarece este banală partajarea codului din cadrul github, prin bifurcarea QGIS, urmată de emiterea cererilor de actualizare.

Verificați întotdeauna că totul se compilează corect, înaintea efectuării cererilor de actualizare. Încercați să conștientizați posibilele defecțiuni pe care le-ar putea produce actualizările dvs. asupra celor care lucrează pe alte platforme, sau cu versiuni mai vechi/mai noi ale bibliotecilor.