Een stap-voor stap bijdrage¶

De GitHub webinterface gebruiken
- Wijzigingen in uw opslagplaats maken
  - Alternatief 1: Een probleem uit de lijst kiezen
  - Alternatief 2: De sneltoets Repareer mij gebruiken
- Deel uw wijzigingen via Pull Request
Gereedschappen voor de opdrachtregel van Git gebruiken

Notitie

Hoewel de QGIS-Documentation wordt gebruikt om het proces te demonstreren, zijn alle hieronder staande opdrachten en stappen ook van toepassing op QGIS-Website.

Nu u weet welke rules te volgen om een helder document voor QGIS te schrijven, zullen we een skijken naar het proce svan het produceren van deze documentatie en hoe snel en veilig uw wijzigingen te delen met de gemeenschap.

Er van uitgaande dat u reeds een GitHub account heeft, dient u eerst de bronbestanden van de documentatie te klonen om een eigen kopie te hebben waarmee u kunt gaan werken: ga naar de pagina QGIS-Documentation repository (voor het gemakt wordt deze opslagplaats hieronder qgis/QGIS-Documentation genoemd) en klik op de knop Fork in de rechter bovenhoek.

Slechts enkele seconden later, zult u in uw GitHub account een opslagplaats QGIS-Documentation vinden (https://github.com/<UwNaam>/QGIS-Documentation). Deze opslagplaats is een veilige kopie waarvoor u volledige schrijfrechten heeft en al u bijdragen kunt maken zonder risico om de officiële documentatie te beïnvloeden. In het begin bevat deze opslagplaats dezelfde takken als qgis/QGIS-Documentation en wordt standaard ingesteld als branch master. Branches (takken) zijn parallelle lijneb van ontwikkeling die verschillende momentopnamen van de documentatie bevatten die kunnen worden samengevoegd of van elkaar verschillen. Maak bij voorkeur een branch voor elk probleem dat u wilt oplossen en u kunt net zoveel branches maken als u wilt.

Tip

Maak uw wijzigingen in een ad hoc branch, nooit in master

Als conventie, probeer het maken van wijzigingen in uw branch master zoveel mogelijk te vermijden, met uitzondering van het samenvoegen van de aanpassingen vanuit de branch master van qgis/QGIS-Documentation (qgis:master genaamd). En gebruik het als model om nieuwe branches te maken voor een schone geschiedenis en snapshot.

Er zijn verschillende manieren om bij te dragen aan de documentatie voor QGIS. Hoewel we ze hieronder afzonderlijk laten zien, zijn zij niet helemaal exclusief, wat betekent dat u, op elk moment, zonder problemen kunt overstappen van het ene proces naar een ander omdat zij beide het schema hieronder volgen:

Maak uw wijzigingen in een ad hoc branch van uw opslagplaats
Publiceer uw wijizigingen en vraag om ze samen te voegen in de hoofd-documentatie door middel van een pull request (PR)
Anderen bekijken, bespreken en integreren uw werk in de hoofdbranch als alles OK lijkt te zijn.

De GitHub webinterface gebruiken ¶

Vanuit uw gekloonde opslagplaats kunt u nu wijzigingen voorstellen aan de hoofd-documentatie. Inderdaad, de GitHub webinterface biedt u daarvoor simpele manieren om:

bestanden te bewerken, te beoordelen en uw wijzigingen in te dienen
maak een pull request om uw wijzigingen ingevoegd te krijgen in de hoofd-opslagplaats
branches te maken, bij te werken of te verwijderen

Lees het GitHub-project Hello-world om enige basis vocabulaire en acties te leren die hieronder zullen worden gebruikt.

Wijzigingen in uw opslagplaats maken ¶

Documentatie kan worden verbeterd door problemen op te lossen die worden genoemd op https://github.com/qgis/QGIS-Documentation/issues of problemen die u tegenkwam toen u door de documentatie bladerde. Zij kunnen van verschillende typen zijn: typefouten, ontbrekend object, verkeerde of gedateerde beschrijving...

Alternatief 1: Een probleem uit de lijst kiezen ¶

Selecteer een issue dat u wilt oplossen. U kunt deelnemers informeren over uw keuze door een opmerking te plaatsen bij het rapport van het probleem en door het aan u toegewezen te krijgen, om te voorkomen dat teveel personen hetzelfde probleem proberen op te lossen.
In uw opslagplaats, maak (en schakel over naar) een branch met een naam die u helpt te onthouden waarover het gaat
Blader door de bronbestanden naar het bestand dat moet worden gewijzigd
Schakel het bestand naar de modus Bewerken met behulp van het pictogram Potlood en maak uw aanpassingen, rekening houdende met guidelines
Valideer uw wijzigingen door het frame filling the Commit Changes te vullen en ze direct in te dienen in uw branch.
Herhaal de vorige stappen voor elk ander bestand dat moet worden bijgewerkt om het probleem op te lossen.

Alternatief 2: De sneltoets `Repareer mij` gebruiken ¶

Het project QGIS verschaft een eenvoudige manier om het brondbestand te benaderen vanuit de online documenatatie. Inderdaad, in plaats van te bladeren door de bronbestanden in GitHub om die te vinden die het probleem bevat, of als u een probleem vindt terwijl u de gebruikershandleiding leest, hoeft u slechts te klikken op de koppeling “Repareer mij” aan de onderzijde van de pagina om het bronbestand te openen in de modus Bewerken.

Dit zal het bestand openen in de branch qgis:master met een bericht aan de bovenzijde dat u mededeelt dat u geen rechten voor schrijven heeft voor deze opslagplaats en dat uw wijzigingen zullen worden toegepast in een nieuwe branch van uw opslagplaats.
Maak uw wijzigingen, waarbij u de richtlijnen volgt die beschikbaar zijn op http://docs.qgis.org/testing/en/docs/documentation_guidelines/
Als u geerd bent kunt u aan de onderzijde van de pagina een opmerking plaatsen over welke wijzigingen u gemaakt heeft en klik daarna op Propose File change. Dit zal een nieuwe branch (patch-xxx) in uw opslagplaats genereren.

Tip

Als uw branch master gelijk is aan de qgis:master, kunt u veilig de koppeling qgis vervangen door <Uw naam>. In dat geval dient u, als de wijzigingen zijn gemaakt, te selecteren radioButtonOn Create a new branch for this commit and start a pull request en het aanpassen van master te vermijden.

Deel uw wijzigingen via Pull Request ¶

Nu heeft u een nieuwe branch in QGIS met een bestand dat afwijkt van qgis:master. U dient een pull request te maken om uw wijzigingen door te voeren in de officiële documentatie.

In feite opent GitHub, nadat u uw wijzigingen hebt ingediend, een nieuw dialoogvenster dat de branches vergelijkt:
- indien u de koppeling Repareer mij gebruikte zonder de URL te wijzigen, dan wordt de vergelijking gemaakt tussen uw branch patch-xxx en de qgis:master (de basis fork is qgis/QGIS-Documentation en de branch master daarvan).
- indien u een branch gebruikte die u zelf een naam had gegeven dan wordt de vergelijking gemaakt tussen die branch en uw eigen branch master (de basis is eenvoudigweg master). U zult daarom die pagina moeten verlaten en de volgende stap volgen.
In elk geval (inclusief het pushen van branch naar GitHub vanaf de opdrachtregel) kunt u op elk moment, vanaf veel pagina;’s, een nieuw pull request maken. Ga eenvoudigweg naar de hoofdpagina van de opslagplaats (die van u of die van QGIS), klik op New Pull Request en Compare across forks (indien nodig). Zorg er voor dat u selecteert qgis/QGIS-Documentation met master als basisbranch en dat de hoofdfork uw opslagplaats <UwNaam>/QGIS-Documentation is met uw aangepaste branch daarin.

Tip

Hoewel uitgegeven en vertaald, wordt de documentatie van QGIS 2.14 nog steeds onderhouden en bestaande problemen worden opgelost. Indien u van plan bent problemen op te lossen in de huidige uitgegeven documentatie, vervang dan de branch master door de van toepassing zijnde branch manual_en_... in een van de eerder uitgelegde stappen.
Een groen vinkje naast de vergelen branches geeft aan dat uw wijzigingen automatisch kunnen worden samengevoegd met de officiële documentatie. Klik op de knop Create pull request. Als u een rood kruis krijgt betekent dat dat de bestanden die u aanpast niet up to date waren met de branch die u als doel gebruikt (een commit is er naartoe gepusht sinds u voor het laatst uw branch bijwerkte op maakte). U dient dan gereedschappen voor de opdrachregel van GIT te gebruiken om het op te lossen.
Vul, indien nodig, het formulier in en klik opnieuw op de knop Create pull request.
Een nieuw PR wordt toegevoegd aan https://github.com/qgis/QGIS-Documentation/pulls en iedereen kan er naar kijken of er een opmerking bij plaatsen.
Dat zal een Travis CI build activeren die automatisch controleert of uw bijdrage geen bouwfouten bevat. In het geval van fouten verschijnt er een rood kruis naast uw commit. Klik eenvoudigweg daarop of op Details in het overzichtsgedeelte aan de onderzijde van de pagina voor de details van de fout. U dient uw gerapporteerde fouten of waarschuwingen te repareren vóórdat uw wijzigingen worden doorgegeven naar de opslagplaats.
Totdat uw PR is samengevoegd met de hoofdopslagplaats, kunt u aanpassingen aanbrengen aan uw verzoek/voorstel. In feite worden nieuwe wijzigingen in uw branch toegepast op uw pull request. Doe dat als de wijziging betrekking heeft op het probleem dat u probeert op te lossen, maak anders een nieuwe branch voor die wijzigingen, gevolgd door de hierboven vermelde stappen.
Als alles er volgens u en anderen goed uitziet, kan een committer uw branch samenvoegen met de hoofdopslagplaats. Uw bijdrage is daarmee gevalideerd.
Als u wilt kunt u nu de branch die u gebruikte verwijderen, om te voorkomen dat teveel (niet gebruikte en gedateerde) branches uw opslagplaats verstoppen.

Door deze kleine stapjes uit te voeren, zult u het proces gemakkelijker leren.

Waarschuwing

Wees alert om het pull request te doen tegen qgis:master en niet uw eigen branch master, anders zal niemand uw wijzigingen zien en zou u per ongeluk uw wijzigingen kunnen samenvoegen met uw branch master, waardoor de geschiedenis wordt besmet.

Tip

Automatisch rapport voor probleem sluiten vanuit pull request

Vermeld het nummer van het probleem dat u wilt oplossen in uw pull request om het beheren van de rapporten van problemen te vereenvoudigen. Dit kan worden gedaan met behulp van #issue_number. Indien voorafgegaan door termen als fix, close... zal het betreffende probleem worden gesloten zodra het pull request is samengevoegd.

Gereedschappen voor de opdrachtregel van Git gebruiken ¶

De webinterface van GitHub helpt u de opslagplaats met uw bijdragen op een eenvoudige manier bij te werken, maar het biedt ook gereedschappen om:

uw commits te groeperen en de geschiedenis van uw wijzigingen op te schonen
conflicten met de hoofdopslagplaats op te lossen, indien nodig...
de documentatie te bouwen om uw wijzigingen te testen

u dient dan git te installeren op uw harde schijf om toegang te verkrijgen tot meer geavanceerde en krachtige programma’s en een lokale kopie van de opslagplaats te krijgen. Sommige basisbeginselen die u vaak nodig heeft worden hieronder besproken. U vindt daar ook regels die u in acht zou moeten nemen, zelfs als u slechts opteert voor de webinterface.

In de voorbeelden van code hieronder, geven lijnen die beginnen met $ opdrachten weer die u zou moeten typen, terwijl # opmerkingen zijn.

Lokale opslagplaats ¶

Nu bent u klaar om een lokale kloon van uw uw opslagplaats QGIS-Documentation op te halen:

$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git

De eerdere opdrachtregel is slechts een voorbeeld. U zou zowel het pad als de URL voor de opslagplaats moeten aanpassen, waarbij <UwNaam> wordt vervangen door uw gebruikersnaam.

Tip

Permission denied (publickey) error?

Indien u een fout Permission denied (publickey) error krijgt, zou er een probleem kunnen zijn met uw sleutel voor SSH. Bekijk GitHub help voor de details.

Controleer het:

$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

origin is de naam van de opslagplaats op afstand van uw opslagplaats voor QGIS-Documentation.
master is de standaard hoofdbranch. U zou die nooit moeten gebruiken om iets in te dienen! Nooit!

U zou hier kunnen beginnen te werken, maar op de lange termijn zou u veel problemen krijgen wanneer u uw bijdragen (Pull Request genaamd in het proces in Github) wilt indien omdat de hoofdbranch van de opslagplaats van QGIS-Documentation af zal wijken van uw lokale opslagplaats of uw opslagplaats op afstand.

Een andere opslagplaats op afstand toevoegen ¶

Voeg een nieuwe opslagplaats op afstand toe aan uw lokale opslagplaats om in staat te zijn het werk in het hoofdproject te volgen. Deze nieuwe opslagplaats op afstand is de opslagplaats QGIS-Documentation van het project QGIS:

$ git remote add upstream git@github.com:qgis/QGIS-Documentation.git
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
upstream        git@github.com:qgis/QGIS-Documentation.git (fetch)
upstream        git@github.com:qgis/QGIS-Documentation.git (push)

U heeft nu dus de keuze tussen twee opslagplaatsen op afstand:

origin om uw lokale branch door te voeren in uw opslagplaats op afstand
upstream om uw bijdragen samen te voegen (als u daar de rechten voor heeft) met de officiële OF om uw hoofdbranch van uw lokale opslagplaats bij te werken vanuit de hoofdbranch van de officiële opslagplaats.

Notitie

upstream is slechts een label, een soort standaard naam, maar u mag het noemen zoals u wilt.

Uw basisbranch bijwerken ¶

Voor het testen van documentatie (branch `master`)¶

Vóórdat u gaat werken aan een nieuwe bijdrage zou u altijd de lokale hoofdbranch in uw lokale opslagplaats moeten bijwerken. Voer gewoon deze opdrachtregel uit:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository
$ git push origin master

Nu heeft u een lokale opslagplaats en een op afstand die beide een branch master hebben die up to date is met QGIS-Documentation van de organisatie van QGIS. U kunt nu aan uw bijdrage gaan werken.

Voor uitgegeven documentatie (branch `manual_en_`)¶

Naast de documentatie voor testen, gaan we ook door met het oplossen van problemen in de documentatie van QGIS 2.14, wat betekent dat u ook daarna kunt bijdragen. Als we de voorbeeld code uit het eerdere gedeelte volgen, kunt u dan eenvoudig doen door de overeenkomende branch te selecteren.

Wanneer u de opslagplaats kloont (zie Lokale opslagplaats), heeft uw kloon alle branches van de opslagplaats op afstand. Zoals hierboven dient u er voor te zorgen dat uw branch up to date is met die op afstand:

# change branch e.g. for 2.14 LTR
$ git checkout manual_en_2.14
# get "information" from the manual_en_2.14 branch in upstream repository
$ git fetch upstream manual_en_2.14
# merge update from upstream/manual_en_2.14 to the current local branch
$ git merge upstream/manual_en_2.14
# update **your** remote repository
$ git push origin manual_en_2.14

Op deze manier zijn uw lokale en branches op afstand voor de versie 2.14 up to date met die van de officiële opslagplaats op afstand.

Aan uw branch voor productie bijdragen ¶

Nu uw basisbranch is bijgewerkt, dient u een toegrwezen branch te maken waarin u uw bijdragen toevoegt. Werk altijd met een andere branch dan de basisbranch! Altijd!

$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
$ git branch
master
manual_en_2.14
* myNewBranch
# a list of existing branch where * means the current branch
# You can now add your contribution, by editing the concerned file
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

Enkele woorden over opdrachten om in te dienen/pushen:

probeer slechts één bijdrage tegelijk in te dienen (atomic change) d.i. heeft betrekking op één probleem
probeer in de titel en beschrijving van uw indiening zorgvuldig uit te leggen wat u gewijzigd. De eerste regel is een titel en zou moeten beginnen met een hoofdletter en bestaat uit een lengte van 80 tekens, eindig niet met een .. Wees beknopt. Uw beschrijving mag langer zijn, eindig die met een . en u kunt veelmeer details geven.
gebruik een # met ene getal om naar een probleem te verwijzen. Zet als voorvoegsel Fix als u het ticket repareert: uw indiening zal het ticket sluiten.

Nu uw wijzigingen zij opgeslagen en doorgevoerd in uw lokale branch, dient u ze door te sturen naar de opslagplaats op afstand door een pull request te maken:

$ git push origin myNewBranch

Uw lokale en opslagplaats op afstand opschonen ¶

Nadat uw PR is samengevoegd met de officiële QGIS-Documentation, kunt u uw branch verwijderen. Als u veel op deze manier werkt zult u binnen een paar weken heel veel nutteloze branches hebben. Houd dus uw opslagplaats op de volgende manier schoon:

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

En vergeet niet de branch master in uw lokale opslagplaats bij te werken!