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.
Now that you know the rules to follow to write a clean doc for QGIS, let’s dive in the process of production of this documentation and how quickly and safely share your changes with the community.
Assuming you already have a GitHub account, you first need to clone the source files of the documentation in order to have your own copy you can work on: go to the QGIS-Documentation repository page (for convenience, this repository is called below qgis/QGIS-Documentation) and click on the Fork button in the upper right corner.
Few seconds later, in your GitHub account you find a QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation). This repo is a safe copy in which you have full write access and can push all your contributions without a risk to affect the official documentation. At the beginning, this repository contains the same branches as qgis/QGIS-Documentation and is defaulted to master branch. Branches are parallel lines of development containing different snapshots of the doc that may merge or diverge. Preferably create a branch for each issue you want to tackle and you can create as many branches as you want.
Tip
Do your changes in an ad’hoc branch, never in master
By convention, avoid making changes in your master branch except merging the modifications from the master branch of qgis/QGIS-Documentation (called qgis:master). And use it as model to create new branches for a clean history and snapshot.
There are different ways to contribute to QGIS documentation. Though we expose them below separately, they are not mutually exclusive, meaning that you can, at any moment, switch from one process to another without any harm because they both follow the scheme below:
From your cloned repository, you can now propose changes to the main documentation. Indeed, GitHub web interface offers you ways to easily:
Lees het GitHub-project Hello-world om enige basis vocabulaire en acties te leren die hieronder zullen worden gebruikt.
Documentation can be improved by addressing issues reported at https://github.com/qgis/QGIS-Documentation/issues or issues you may have encountered while browsing the doc. They can be of different types: typo error, missing feature, wrong or out of date description...
The QGIS project provides an easy way to reach source file from online documentation. Indeed, instead of browsing the source files in GitHub to find the one that suits the issue, or if you find an issue while reading the manuals, you simply have to click the “Fix Me” link at the bottom of the page to open its source file in Edit mode.
This will open the file in the qgis:master branch with a message at the top of the page telling you that you don’t have write access to this repo and your changes will be applied in a new branch of your repository.
Note that if you have commit rights to QGIS-Documentation repository, then no message will show and you’ll directly modify qgis:master branch itself unless you save your changes in another branch.
Do your changes following guidelines available at http://docs.qgis.org/testing/en/docs/documentation_guidelines/
When you finish, at the bottom of the page, comment a bit what your changes are about and click on Propose File change. This will generate a new branch (patch-xxx) in your repo.
Tip
If your master branch is even with qgis:master, you can safely replace in the link qgis by <YourName>. In this case, once your changes are done, you need to check Create a new branch for this commit and start a pull request and avoid modifying master.
GitHub web interface helps you update the repo with your contribution in an easier way but it doesn’t offer tools to:
de documentatie te bouwen om uw wijzigingen te testen
You then need to install git on your hard drive in order to get access to more advanced and powerful tools and have a local copy of the repository. Some basics you may often need are exposed below. You’ll also find rules to care about even if you opt for the web interface.
In de voorbeelden van code hieronder, geven lijnen die beginnen met $ opdrachten weer die u zou moeten typen, terwijl # opmerkingen zijn.
Nu bent u klaar om een lokale kloon van uw uw opslagplaats QGIS-Documentation op te halen:
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<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 [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin [email protected]:<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.
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 [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream [email protected]: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.
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.
Along the testing documentation, we continue to fix issues in QGIS 2.18 doc, meaning that you can also contribute to it. Following the previous section sample code, you can easily do that by selecting the corresponding branch.
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
In this way your local and remote branches for the 2.14 version are up to date with the one of the official upstream repository.
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 zijn opgeslagen en doorgevoerd in uw lokale branch, dient u ze door te sturen naar de opslagplaats op afstand om een pull request te maken:
$ git push origin myNewBranch
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!