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.
Gebruikers van de op Debian gebaseerde distributie kunnen:
sudo apt-get install git
Windows users can obtain msys git or use git distributed with cygwin.
The git project has a downloadable build of git. Make sure to get the package matching your processor (x86_64 most likely, only the first Intel Macs need the i386 package).
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 the source from http://git-scm.com/. Unzip it, and in a Terminal cd to the source folder, then:
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=
Om een clone te maken van QGIS master:
git clone git://github.com/qgis/QGIS.git
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.
Wanneer je de broncode van de QGIS documentatie wilt uitchecken:
git clone [email protected]:qgis/QGIS-Documentation.git
Je kunt ook de readme lezen welke onderdeel is van de documentatie repository voor meer informatie.
Wanneer je de broncode van de QGIS website wilt uitchecken:
git clone [email protected]:qgis/QGIS-Website.git
Je kunt ook de readme lezen welke onderdeel is van de website repository voor meer informatie.
De volgende websites bevatten informatie om een Git master te worden.
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 QGIS project 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 gemerged nadat deze gereed en stabiel zijn. Dit deel beschrijft de procedure branching en merging van broncode in het QGIS project.
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
It is also recommended to document the intended changes and the current status of the work on a wiki page.
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.
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.
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 te mergen naar uw PR branch (= pull request branch), zodat wijzigingen vanuit uw PR branch altijd upstream zijn te mergen naar de 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
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.
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!
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.
Optie A:
klik op de knop Merge (maakt een ‘non-fast-forward merge’ aan)
Optie B:
Testen (Uiteraard ook vereist voor option A)
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)
If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. bug777fix.patch, and attach it to the original bug report in trac.
If the bug is an enhancement or new feature, its usually a good idea to create a ticket in trac first and then attach your patch.
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.
QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you - using the Technical Resources and contact them asking them if they can look at your patch. If you don’t get any response, you can escalate your query to one of the Project Steering Committee members (contact details also available in the Technical Resources).
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.
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.