Toegang met Git

Dit deel beschrijft hoe je kunt beginnen met het gebruiken van de QGIS Git repository. Eerst heb je een op je systeem geïnstalleerde Git client nodig.

Installatie

Installeer Git voor GNU/Linux

Gebruikers van de op Debian gebaseerde distributie kunnen:

sudo apt install git

Installeren van Git voor Windows

Windows gebruikers kunnen Git verkrijgen via msys git of gebruik git gedistribueerd met cygwin.

Installeer Git voor OSX

Het git project heeft een te downloaden build van GIT. Zorg er voor dat u het pakket krijgt dat overeenkomt met uw processor (meest waarschijnlijk x86_64, alleen de eerste Intel Mac’s hadden het pakket i386 nodig).

Na het downloaden op het disk image en start de installer.

PPC/source notitie

De Git site heeft geen PPC installatiepakket. Wanneer je Git wilt installeren op een PPC dan moet je deze zelf compileren waarbij je wel meer controle hebt over de installatie.

Download de bron van https://git-scm.com/. Unzip het, en cd in een Terminal naar de map source, dan:

make prefix=/usr/local
sudo make prefix=/usr/local install

Wanneer je de extra’s, Perl, Python of TclTk (GUI), niet nodig hebt kun je deze uit de build met make houden door:

export NO_PERL=
export NO_TCLTK=
export NO_PYTHON=

Toegang tot de repository

Om een clone te maken van QGIS master:

git clone git://github.com/qgis/QGIS.git

Uitchecken van een branch

Om een branch uit te checken, bijvoorbeeld de 2.6.1 branch doe:

cd QGIS
git fetch
git branch --track origin release-2_6_1
git checkout release-2_6_1

Om de master branch uit te checken:

cd QGIS
git checkout master

Notitie

Voor QGIS wordt er voor elke uitgebrachte versie van QGIS een release branch gemaakt. Master bevat de laatste versie van QGIS, de zogenaamde ‘unstable’ release. Wanneer een nieuwe versie wordt aangemaakt 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.

Zie het bestand INSTALL in de root van de broncode voor specifieke instructies voor het bouwen van ontwikkel versies van QGIS.

QGIS documentatie broncode

Wanneer je de broncode van de QGIS documentatie wilt uitchecken:

git clone git@github.com:qgis/QGIS-Documentation.git

Je kunt ook de readme lezen welke onderdeel is van de documentatie repository voor meer informatie.

QGIS website broncode

Wanneer je de broncode van de QGIS website wilt uitchecken:

git clone git@github.com:qgis/QGIS-Website.git

Je kunt ook de readme lezen welke onderdeel is van de website repository voor meer informatie.

Git documentatie

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

Ontwikkeling in branches

Doel

De QGIS broncode is toegenomen en ingewikkelder geworden in de afgelopen jaren. 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 waar de nieuwe functionaliteit eerst werd ontwikkeld in Git Branches en daarna pas in de master branch worden samengevoegd, nadat deze gereed en stabiel zijn. Dit gedeelte beschrijft de procedure branching en samenvoegen van broncode in het project QGIS.

Procedure

  • Initiële aankondiging op de mailinglijst:

    Voordat men begint, plaats een aankondiging op de ‘qgis-developer’ mailing list voor ontwikkelaars om te zien of een andere ontwikkelaar mogelijk al werkt aan dezelfde functionaliteit. Neem ook contact op met de technisch adviseur van het ‘Project Steering Committee’ (PSC). Als de nieuwe mogelijkheid wijzigingen vereist aan de architectuur van QGIS is een ‘request for comment’ (RFC) nodig.

Maak een branch: Maak een nieuwe Git branch aan voor de ontwikkeling van de nieuwe functionaliteit.

git checkout -b newfeature

Nu kunt u beginnen met de ontwikkeling. Als u van plan bent groot uit te pakken in die branch, u werk zou willen delen met andere ontwikkelaars, en schrijftoegang nodig heeft naar de upstream repository, kunt u uw repository pushen naar de officiële QGIS repository met:

git push origin newfeature

Notitie

Als de branch al bestaat zullen uw wijzigingen daarin worden gepusht.

Voer regelmatig een ‘rebase’ uit vanuit 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. Na een ‘rebase’ gebruik git push -f naar uw gevorkte repository.

Notitie

Gebruik nooit git push -f naar de origin repository! Gebruik deze opdracht alleen voor het bijwerken van uw werk-branch.

git rebase master

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.

Het indienen van Patches en Pull Requests

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.

Pull Requests

In het algemeen is het voor ontwikkelaars gemakkelijker wanneer u pull requests bij GitHub indient. We beschrijven hier niet het uitvoeren van ‘pull requests’, maar verwijzen daarvoor naar de documentatie van GitHub over ‘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

Bekijk het gedeelte hieronder over ‘hoe aandacht voor uw patch te krijgen’. In het algemeen is het zo dat als u een PR indient u ook de verantwoordelijkheid moet nemen om deze te volgen totdat deze is voltooid - beantwoord vragen die door andere ontwikkelaars zijn gepost, zoek een ‘kampioen’ voor uw mogelijkheid en geef ze af en toe een vriendelijke herinnering als u ziet dat er geen actie wordt ondernomen met betrekking tot uw PR. Onthoud wel dat het project QGIS wordt uitgevoerd door inspanningen van vrijwilligers en mensen zijn mogelijk niet in staat om direct te reageren op uw PR. Als u van mening bent dat uw PR niet de aandacht krijgt die het verdient, zijn uw opties om daar wat vaart in te brengen (in volgorde van prioriteit):

  • 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.

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 je een pull verzoek uitvoert geef eerst de opdrachten git fetch origin en git rebase origin/master (gegeven origin verwijst naar de ‘remote’ voor ‘upstream’ 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!

Speciale labels om schrijvers van documentatie te informeren

Naast algemene tags die u kunt toevoegen om uw PR te classificeren, zijn er speciale tags die u kunt gebruiken om automatisch issue rapporten te genereren in de repository van de QGIS-Documentation zodra uw pull request is gemerged:

  • [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.

Voor het uitvoeren van een merge van een pull request

Optie A:

  • klik op de knop Merge (maakt een ‘non-fast-forward merge’ aan)

Optie B:

  • Doe een checkout van de pull request

  • Testen (Uiteraard ook vereist voor option A)

  • checkout master, git merge pr/1234

  • Optioneel: git pull --rebase: maakt een “fast-forward, no merge commit” aan. Dit levert een schonere historie op, maar het is moeilijker om de commit ongedaan te maken.

  • git push (gebruik hier NOOIT de -f optie)

Naamgeving voor patch bestanden

Als de patch een reparatie is voor een specifieke bug, geef het bestand dan een naam met het nummer van de bug erin bijv. bug777fix.patch, en maak het een bijlage van het originele bug report in GitHub.

Als de bug een verbetering of een nieuwe mogelijkheid is, is het gewoonlijk een goed idee om eerst een ticket in GitHub te maken en uw patch als bijlage daaraan toe te voegen.

Een patch aanmaken in de top folder van de QGIS broncode

Dit maakt het voor ons gemakkelijker om de patches door te voeren omdat we niet hoeven te navigeren naar een specifieke folder van de broncode om de patch door te voeren. Wanneer ik patches ontvang, evalueer ik ze met behulp van een merge, wanneer de patch in de top-folder staat maakt dit veel gemakkelijker. Hieronder is een voorbeeld gegeven hoe u meerdere gewijzigde bestanden kunt opnemen in uw patch vanuit de top-folder:

cd QGIS
git checkout master
git pull origin master
git checkout newfeature
git format-patch master --stdout > bug777fix.patch

Dit zal er voor zorgen dat uw master branch in-sync is met de upstream repository, en hoe vervolgens een patch kan worden aangemaakt die de wijzigingen bevat tussen jouw ‘feature branch’ en de master branch.

Aandacht krijgen voor uw patch

Ontwikkelaars van QGIS zijn drukke mensen. We scannen de inkomende patches voor bugrapporten maar soms missen we dingen. Wees daardoor niet beledigd of bang. Probeer een ontwikkelaar te identificeren die u kan helpen en neem contact met ze op en vraag of zij naar uw patch willen kijken. Als u geen antwoord krijgt, kunt u uw vraag escaleren naar een van de leden van het Project Steering Committee (contactdetails ook beschikbaar in de Technical Resources).

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.

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.

Tijdens een commit, zal uw teksteditor (zoals gedefinieerd in de omgevingsvariabele $EDITOR) verschijnen en je zou commentaar moeten toevoegen aan het begin van het bestand (Voor de regel met ‘don’t change this’). Geef beschrijvend commentaar maak liever verscheidene kleinere commits wanneer de wijzigingen over verschillende bestanden niet gerelateerd zijn. Daarnaast prefereren we u om gerelateerde wijzigingen wel in één enkele commit te groeperen indien mogelijk.