3. Ontwikkelingsproces

Zoals gewoonlijk in openbron-projecten worden bijdragen van code en documentatie voor het project bijzonder op prijs gesteld. De gemeenschap van QGIS is bijzonder ondersteunend. Dit gedeelte beschrijft de procedure voor het ontwikkelen en samenvoegen van uw bijdragen in het project QGIS.

3.1. Een op git gebaseerd project

De complexiteit van de QGIS broncode is in de afgelopen jaren aanzienlijk toegenomen. Het is dan ook moeilijk om alle negatieve bijwerkingen te overzien die het toevoegen van nieuwe functionaliteit zal hebben. In het verleden had het project QGIS lange release-cyclussen, omdat het veel werk was om het systeem weer stabiel te krijgen na het toevoegen van nieuwe functionaliteit. Om deze problemen te voorkomen is er overgestapt naar een nieuw ontwikkelingsmodel git versiebeheerssysteem: de nieuwe functionaliteit worden eerst gecodeerd in branches van gebruikers en worden daarna pas in de masterbranch samengevoegd, als zij gereed en stabiel zijn.

Broncode van QGIS wordt gehost op https://github.com/qgis/QGIS.

3.1.1. Rollen

Er bestaan verscheidene rollen in GitHub. Wanneer u al een account hebt voor GitHub kunt u al bijdragen door de repository te forken en heeft u de rol ‘contributor’. Ontwikkelaars van de bron zijn ‘collaborators’ en kunnen branches samenvoegen met de upstream en officiële repository.

3.1.2. Omgeving

U moet, om te kunnen beginnen met en bij te dragen aan de opslagplaats van QGIS,:

  1. een GitHub account hebben

  2. maak uw eigen kopie van de opslagplaats van QGIS (bekijk fork)

  3. een git cliënt hebben geïinstalleerd op uw systeem

  4. stel uw eigen omgeving voor git in

  5. en vooral veel plezier hebben!

3.1.3. Git installeren

Het project Git verschaft recente versies van de software voor de meeste platformen. Volg de instructies op https://git-scm.com/downloads om de kopie te krijgen en te installeren die overeenkomt met uw besturingssysteem en architectuur. Daar is het ook mogelijk om een Git GUI-cliënt te installeren om te bladeren en uw opslagplaatsen te beheren (meestal zal het git installeren, tenzij niet beschikbaar).

3.2. Ontwikkeling in branches

3.2.1. Bijdragen aan ontiwkkeling

Eenmaal aangemeld bij GitHub en de opslagplaats t ehebben geforkt, kunt u bijdragen als een deelnemer.

Notitie

Bijdragen aan de code van QGIS kunnen worden gedaan vanuit uw geforkte opslagplaats naar de website van GitHub. De nieuwe code zal automatisch worden gebouwd door de testomgeving. Maar deze werkstroom kan snel zijn beperkingen tonen wanneer u complexe wijzigingen wilt inbrengen. Instructies hieronder gaan uit van een lokale kloon.

U kunt bijdragen door een pull request te initiëren. Volg deze algemene stappen om dat te doen:

  1. Kloon uw opslagplaats naar uw lokale computer en stel de bouwomgeving in

  2. Maak een nieuwe nieuw branch en doe daar de bewerkingen voor de ontwikkeling

  3. Commit uw wijzigingen en push uw branch terug naar de fork op afstand op GitHub. Een pull request wordt dan direct daarna aangeboden als weblink (URL).

  4. Open een pull request (PR) en vraag om de commit(s) vanuit uw branch te pullen in de master branch in de upstream repository.

  5. Een proces voor nakijken wordt gestart dat andere contributors en collaborators informeert over uw pull request. U wordt geacht te reageren op hun opmerkingen en suggesties.

Notitie

Een meer gedetailleerde Github’s Fork & Pull Workflow is beschikbaar op https://reflectoring.io/github-fork-and-pull/

Notitie

De meeste projecten van QGIS (website, documentatie, pyQGIS API, plug-ins…) zijn beschikbaar op de project GitHub pagina en kan bijdragen ontvangen, daarbij hetzelfde proces volgend.

3.2.2. Toegang tot de repository

U moet, om vanaf uw lokale schijf te kunnen werken met zowel uw remote fork als de QGIS upstream repositories:

  1. Een kloon van uw kopie maken op uw lokale schijf

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

  2. De hoofdopslagplaats van QGIS (we zullen die upstream noemen) verbinden met die van u

    git remote add upstream https://github.com/qgis/QGIS.git

  3. Verbonden opslapgplaatsen op afstand controleren

    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)

    Uw online opslagplaats is nu toegankelijk vanaf uw lokale schijf en u kunt ermee werken door de naam origin te gebruiken. Elke keer als u wijzigingen zou willen ophalen vanuit de opslagplaats van qgis/QGIS, gebruik dan upstream.

Notitie

In QGIS bewaren we onze meest stabiele code in de huidige releasebranch. Branch ``master``bevat de code voor de zogenaamde ‘unstable’ releaseserie. Periodiek zal er ook een nieuwe branch vanuit master worden aangemaakt, vervolgens wordt deze verder stabiel gemaakt en wordt er selectief nieuwe functionaliteit aan master toegevoegd.

Bekijk het bestand INSTALL in de boom van de bron voor specifieke instructies voor het bouwen van ontwikkelingsversies.

3.2.3. Procedure

  1. Initiële aankondiging op de mailinglijst of bij bestaand probleem in opslagplaats:

    Voordat men begint, plaats een aankondiging op de mailinglijst voor ontwikkelaars om te zien of een andere ontwikkelaar mogelijk al werkt aan dezelfde functionaliteit. U kunt ook uw interesse vermelden als een opmerking in het probleemrapport als dat bestaat in de opslagplaats. Als de nieuwe mogelijkheid wijzigingen vereist aan de architectuur van QGIS is een QGIS Enhancement Proposal (QEP) nodig.

  2. Een branch maken in uw lokale opslagplaats:

    Maak een nieuwe Git branch aan voor de ontwikkeling van de nieuwe functionaliteit, gebaseerd op de laatste status van de branch master.

    git fetch upstream master
git checkout -b newfeature upstream/master
  3. Nu kunt u beginnen met ontwikkelen:

    Codeer uw wijzigingen op uw lokale schijf met uw normale IDE. Onthoud om testsuites te schrijven voor uw aanpassingen, indien van toepassing.

  4. Commit uw wijzigingen in de opslagplaats van git:

    Geef, bij het maken van een commit, beschrijvend commentaar en maak liever verscheidene kleinere commits als de wijzigingen voor verschillende bestanden niet gerelateerd zijn. Daarnaast prefereren we om gerelateerde wijzigingen wel in één enkele commit te groeperen, indien mogelijk.

    git add path/to/your/files
git commit -m "Add a comment describing your nice feature"

  5. Nu zou u uw werk willen delen met leden van de gemeenschap van QGIS. Push uw nieuwe functionaliteit naar uw online fork-opslagplaats door:

    git push origin newfeature

    Notitie

    Als de branch al bestaat zullen uw wijzigingen daarin worden gepusht. anders wordt hij gemaakt.

  6. Dien uw wijzigingen in met een pull-request

    Door het openen van het pull-request wordt de geautomatiseerde testsuite geactiveerd en controleert of uw wijzigingen de richtlijnen voor coderen in QGIS volgen en geen bestaande functionaliteit beschadigen. U zou gerapporteerde problemen moeten repareren voordat uw branch met upstream wordt samengevoegd.

    Tip

    We gebruiken GitHub acties om de testen te beheren die moeten worden uitgevoerd op de opslagplaats. Voor het gemak kunt u de acties inschakelen op uw opslagplaats zodat de testen worden uitgevoerd wanneer u de wijzigingen pusht. U zou dan het pull request moeten openen nadat ze allemaal zijn uitgevoerd, wat het proces van nakijken efficiënter maakt.

  7. Rebase regelmatig naar upstream master:

    Het wordt aanbevolen om op een regelmatige basis de wijzigingen in de master samen te voegen met de branch met een ‘rebase’. Dat maakt het later eenvoudiger om wijzigingen vanuit de branch met een ‘merge’ toe te voegen in de master branch. Gebruik, na een ‘rebase’, git push -f naar uw geforkte repository.

    git pull --rebase upstream master
git push -f origin newfeature

Notitie

De volgende websites bevatten informatie om een Git master te worden.

3.2.4. Testen voor het uitvoeren van een ‘merge’ om wijzigingen terug naar master te brengen

Wanneer u gereed bent met de ontwikkeling van de nieuwe functionaliteit en tevreden bent met de stabiliteit, maak een aankondiging op de lijst voor ontwikkelaars. Vóór het terug mergen van wijzigingen, zullen de wijzigingen worden getest door ontwikkelaars en gebruikers.

3.3. Pull Requests indienen

Er zijn een aantal richtlijnen, die u helpen om uw patches en pull requests eenvoudig in QGIS te krijgen, en ons helpen met het verwerken van patches die naar ons worden gestuurd.

Over het algemeen is het voor ontwikkelaars gemakkelijker als u pull requests voor GitHub indient. We beschrijven Pull Requests hier niet, maar verwijzen u in plaats daarvan naar de `documentatie voor GitHub pull request https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_.

Wanneer u een pull request indient vragen we u om regelmatig wijzigingen vanuit master samen te voegen naar uw PR branch (= pull request branch), zodat wijzigingen vanuit uw PR branch altijd upstream zijn samen te voegen naar de master branch.

Als u een ontwikkelaar bent en de rij van de pull requests wilt bekijken, is er een aardig programma dat u dat laat doen vanaf de opdrachtregel

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 bij het nakijken van pull requests van anderen, om de persoon, die aan het uwe is toegewezen, vrij te houden.

  • Stuur een bericht naar de mailinglijst om uw PR ‘aan de man te brengen’ en hoe mooi het zou zijn om die onderdeel te maken van de basis code.

  • Stuur een bericht naar de persoon aan wie jouw PR is toegewezen in de PR lijst.

  • Stuur een bericht naar Marco Hugentobler (hij beheert de PR lijst).

  • Stuur een bericht naar de project stuur groep (project steering committee) met de vraag of zij hulp kunnen bieden bij het opnemen van jouw PR in de basis code.

3.3.1. Beste manier voor het aanmaken van een pull request.

  • Start altijd met het aanmaken van een ‘feature branch’, branch waarin de nieuwe functionaliteit wordt ontwikkeld, vanuit master.

  • Wanneer je ontwikkeld in de ‘feature branch’, gebruik dan geen merge voor het bijwerken van die branch, maar een rebase zoals beschreven in volgende punt, om zo jouw geschiedenis schoon te houden.

  • Voordat u een pull verzoek uitvoert geef eerst de opdrachten git fetch origin en git rebase origin/master (gegeven upstream is de remote voor de gebruiker van qgis en niet jouw eigen remote, controleer jouw .git/config of geef de opdracht git remote -v | grep github.com/qgis).

  • U kunt een git rebase, zoals vermeld in de laatste regel, herhaaldelijk uitvoeren zonder schade (zolang als het enige doel is om de wijzigingen uit uw branch gemerged te krijgen in master).

  • Attentie: Na een rebase dient u git push -f uit te voeren op uw gevorkte repository. CORE DEVS: DOE DIT NIET OP DE QGIS PUBLIC REPOSITORY!

3.3.2. Speciale labels om schrijvers van documentatie te informeren

Er is een speciaal label (Needs Documentation) dat kan worden toegewezen door reviewers aan uw pull request om automatisch issue-rapporten te genereren in de repository van QGIS-Documentation zodra uw pull request is gemergd. Vergeet niet te vermelden of uw functionaliteit een dergelijk label verdient.

Meer nog, u kunt speciale tags toevoegen aan uw berichten voor commits om meer informatie te verschaffen aan schrijvers van documentatie. Het bericht voor de commit wordt dan toegevoegd aan het gemaakte issue-rapport:

  • [needs-docs] is een verzoek aan de schrijvers van documentatie om aanvullende documentatie toe te voegen na een reparatie of uitbreiding op een bestaande functionaliteit.

  • [feature] in het geval van nieuwe functionaliteit. Het invullen van een goede beschrijving van uw PR is een goed begin.

Ontwikkelaars wordt gevraagd deze labels (niet hoofdlettergevoelig) te gebruiken zodat schrijvers van documentatie issues binnenkrijgen zodat zij een overzicht hebben van werk dat gedaan moeten worden. Ook belangrijk, neem de tijd om een beschrijving toe te voegen, ofwel in de commit of in de documentatie.

3.3.3. Betracht gepaste zorgvuldigheid

QGIS is gelicenseerd onder de GPL. U dient er u uiterste best voor te doen om te zorgen dat u alleen patches indient waarover geen conflicten kunnen ontstaan met betrekking tot rechten over intellectueel eigendom. Dien ook geen broncode in wanneer u niet tevreden met de gedachte dat deze eveneens beschikbaar komt onder de GPL licentie.

3.4. Het verkrijgen van Git schrijftoegang

Directe schrijftoegang tot de QGIS broncode wordt gegeven door uitnodiging. Wanneer een persoon meerdere (geen vastgesteld aantal) substantiële wijzigingen heeft ingediend die aangeven dat deze C++ en de QGIS coding conventions beheerst, kan een lid van de PSC of een van de andere ontwikkelaars voorstellen om schrijfrechten te verlenen. Diegene die iemand voordraagt moet schriftelijk een promotiestukje indienen waarom diegene schrijfrechten zou moeten krijgen. In sommige gevallen geven we schrijfrechten aan niet C++ ontwikkelaars bijvoorbeeld aan vertalers en schrijvers van documentatie. In die gevallen moet de persoon in kwestie hebben aangetoond dat deze patches kan indienen en bij voorkeur al enkele substantiele patches ingedient die duidelijk maken dat de persoon wijzigingen kan maken in de basis repository zonder nieuwe problemen te introduceren, enz.

Notitie

Sinds de overgang naar GIT geven we minder snel schrijftoegang aan nieuwe ontwikkelaars omdat het eenvoudig is de code te delen binnen GitHub door een fork (een persoonlijke online kopie van QGIS project repository binnen GitHub) aan te maken en vervolgens wijzigingen via pull requests in te dienen.

Controleer altijd of alles compileert vóór het maken van commit / pull request. Ben er continue bewust van dat jouw commit mogelijk problemen veroorzaakt voor mensen die bouwen op andere platformen met oudere / nieuwere versies van functie bibliotheken.