Viktigt
Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.
1. Ett steg för steg-bidrag
Observera
Även om QGIS-Documentation används för att demonstrera processen, gäller alla kommandon och steg som visas nedan även för QGIS-Website.
Om du läser dessa rader är det säkert för att du är villig att bidra till att skriva QGIS-dokumentation och letar efter en how-to. Då har du kommit till rätt ställe! Detta dokument kommer att vägleda dig genom de olika sätten att uppnå detta mål, visa dig de viktigaste stegen att följa, de knep du kan använda och de fällor du bör vara medveten om.
Om du behöver hjälp, tveka inte att antingen fråga i en kommentar till den problemrapport som du försöker åtgärda eller skriv till listan QGIS-community-team. Läs allmän information om QGIS community support.
Låt oss nu dyka in i processen.
Dokumentationskällorna lagras med hjälp av versionshanteringssystemet git och finns tillgängliga på GitHub på https://github.com/qgis/QGIS-Documentation. En lista över problem som ska åtgärdas och funktioner som ska förklaras finns på https://github.com/qgis/QGIS-Documentation/issues.
Tips
Om du är en förstagångsmedarbetare och inte vet var du ska börja, kanske du är intresserad av att ta itu med våra ”välkomstrapporter” <https://github.com/qgis/QGIS-Documentation/contribute>`_.
Det finns två huvudsakliga sätt, som inte utesluter varandra, att ändra filerna:
1.1. Använda GitHubs webbgränssnitt
Med GitHubs webbgränssnitt kan du göra följande:
redigera filer
förhandsgranska och bekräfta dina ändringar
göra en pull request för att få dina ändringar införda i huvudarkivet
skapa, uppdatera eller ta bort grenar
Om du ännu inte är bekant med git och GitHub-vokabulär kan du läsa GitHub-projektet Hello-world för att lära dig grundläggande vokabulär och åtgärder som kommer att användas nedan.
Observera
Om du åtgärdar ett rapporterat problem
Om du gör ändringar för att åtgärda ett problem, lägg till en kommentar till problemrapporten för att tilldela den till dig själv. Detta förhindrar att mer än en person arbetar med samma problem.
1.1.1. Gaffel QGIS-dokumentation
Förutsatt att du redan har ett GitHub-konto, måste du först forka källfilerna för dokumentationen.
Navigera till sidan QGIS-Documentation repository och klicka på knappen 
i det övre högra hörnet.
I ditt GitHub-konto hittar du ett QGIS-Documentation-arkiv (https://github.com/<YourName>/QGIS-Documentation). Detta arkiv är en kopia av det officiella QGIS-Documentation-arkivet där du har full skrivåtkomst och kan göra ändringar utan att påverka den officiella dokumentationen.
1.1.2. Gör ändringar
Det finns olika sätt att bidra till QGIS-dokumentationen. Vi visar dem separat nedan, men du kan byta från den ena processen till den andra utan att det gör någon skada.
Alternativ 1: Använd genvägen Edit on GitHub
Sidor på webbplatsen för QGIS-dokumentation kan redigeras snabbt och enkelt genom att klicka på länken ”Redigera på GitHub”:
längst upp till höger på varje sida,
eller i rullgardinsmenyn längst ner i vänster sidofält.
Detta öppnar filen i grenen
qgis:mastermed ett meddelande högst upp på sidan som talar om att du inte har skrivbehörighet till det här arkivet och att dina ändringar kommer att tillämpas på en ny gren av ditt arkiv.Gör dina ändringar. Eftersom dokumentationen är skriven med hjälp av reStructureText-syntaxen kan du, beroende på dina ändringar, behöva förlita dig på writing guidelines.
När du är klar med att ändra filen trycker du på Commit changes… och lägger till en kort titel som förklarar dina ändringar. Du kan också ge en mer detaljerad förklaring, om det behövs.
Tryck på Föreslå ändringar och spara ändringarna i ditt arkiv. Detta kommer att generera en dedikerad gren (
patch-xxx) i ditt arkiv och webbläsaren kommer att öppna sidan Jämför ändringar.Om problemet du tar upp inte behöver några ytterligare ändringar kan du hoppa till avsnittet Dela dina ändringar via Pull Request nedan.
Om det finns ytterligare ändringar som du vill göra innan du skickar dem till QGIS, följ dessa steg:
Navigera till din förgrening av QGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation)Klicka på
och sök efter den nya grenen patch-xxx.Välj den. Knappen
kommer nu att visa Branch: patch-xxx.Hoppa ner till avsnittet Modifiera filer nedan.
Alternativ 2: Skapa en ad hoc-gren i ditt dokumentationsarkiv
Du kan redigera filer direkt från din del av QGIS-dokumentationen.
Se först till att din master-gren är uppdaterad med uppströms, dvs. qgis/QGIS-Documentation:master-grenen. För att göra detta:
Gå till huvudsidan för ditt arkiv, d.v.s.
https://github.com/<YourName>/QGIS-Documentation. Grenenmasterbör vara aktiv med ett omnämnande om huruvida den är uppdaterad medqgis/QGIS-Documentation:mastereller inte.Om den har överföringar före uppströmsgrenen är det bättre att du använder den tidigare genvägsknappen alternativ tills du anpassar din
master-gren.Om det bara har åtaganden bakom sig:
Expandera rullgardinsmenyn Sync fork till höger. Det kan du göra:
Jämför grenarna och se nya ändringar i uppströmsgrenen som du ännu inte har i din egen
Fetch and merge: tar med ändringar från uppströmsgrenen till din.
Klicka på Fetch and merge: efter processen nämns din gren som uppdaterad med
qgis/QGIS-Documentation:master.
Klicka på
i det övre vänstra hörnet av ditt förgrenade QGIS-Documentation-arkiv och ange ett unikt namn i textfältet för att skapa en ny gren. Det rekommenderas att namnet på den nya grenen relaterar till det problem du tänker åtgärda. Det är praktiskt för att identifiera grenen senare.Tryck på Create branch <branch_name> from master. Knappen
ska nu visa branch_name.Du är redo att påbörja nya ändringar ovanpå din nya gren.
Uppmärksamma
Gör dina ändringar i en ad hoc-gren, aldrig i master grenen
Enligt konvention ska du undvika att göra ändringar i din master-gren utom när du sammanfogar ändringarna från master-grenen av qgis/QGIS-Documentation till din kopia av QGIS-Documentation-arkivet. Separata grenar gör att du kan arbeta på flera problem samtidigt utan att störa andra grenar. Om du gör ett misstag kan du alltid ta bort en gren och börja om genom att skapa en ny från huvudgrenen.
1.1.3. Ändra filer
Kontrollera att den gren du vill ändra är aktiv: dess namn visas i menyn längst upp till vänster eller i sidans URL.
Bläddra igenom källfilerna till den fil som behöver ändras.
Tryck på knappen
Edit this file.Uppdatera texten enligt skrivriktlinjerna
När du är klar med att ändra filen trycker du på Commit changes… och lägger till en kort titel som förklarar dina ändringar. Du kan också ge en mer detaljerad förklaring, om det behövs.
Kontrollera att Commit directly to the <branch_name> branch är valt.
Tryck på Commit changes för att spara dina ändringar i grenen.
För att uppdatera eller lägga till en ny bildfil:
Bläddra i din gren till mappen med den fil som ska uppdateras eller läggas till.
Längst upp till höger kan du använda menyn för att välja och ladda filer från din hårddisk. Tips om hur du formaterar en bild för dokumenten finns i Hantera skärmdumpar.
Om det redan finns en fil med samma namn skrivs den över.
Bekräfta återigen dina ändringar till målgrenen.
Upprepa de föregående stegen för alla andra filer som behöver uppdateras för att åtgärda problemet.
1.1.4. Dela med dig av dina ändringar via Pull Request
Du måste göra en pull request för att integrera dina ändringar i den officiella dokumentationen.
Starta en ny pull request
Om du använde länken
Edit on GitHuböppnar GitHub automatiskt en ny sida efter att du har bekräftat dina ändringar, där ändringarna i din grenpatch-xxxjämförs med grenenqgis/QGIS-Documentation:master.I samtliga fall kan sidan för jämförelse av ändringar nås genom att gå till sidan ”Pull requests” i ditt arkiv och klicka på New pull request.
Jämför förändringar
Om du ser två dialogrutor, en som säger base:master och den andra compare:branch_name (se figur), kommer detta bara att slå samman dina ändringar från en av dina grenar till din huvudgren. För att åtgärda detta klickar du på länken compare across forks.
Fig. 1.8 Om din sida Comparing changes ser ut så här, klicka på länken compare across forks.
Du bör se fyra rullgardinsmenyer. Med hjälp av dessa kan du jämföra de ändringar som du har gjort i din gren med den huvudgren som du vill slå samman med. De är följande:
base fork: den fork som du vill slå samman dina ändringar med
base: den gren av basgaffeln som du vill slå samman dina ändringar med
huvudgaffel: den gaffel som har ändringar som du vill införliva i basgaffeln
jämför: grenen med dessa ändringar
Välj qgis/QGIS-Documentation som basgaffel med master som bas, sätt huvudgaffeln till ditt arkiv <YourName>/QGIS-Documentation, och sätt compare till din modifierade gren.
Fig. 1.9 Jämförelse av ändringar mellan qgis/QGIS-Documentation och ditt arkiv
En grön bock med orden Able to merge visar att dina ändringar kan sammanfogas till den officiella dokumentationen utan konflikter.
Klicka på knappen Create pull request.
Varning
Om du ser 
Detta innebär att det finns konflikter. Filerna som du ändrar är inte uppdaterade med den gren du riktar in dig på eftersom någon annan har gjort en commit som står i konflikt med dina ändringar. Du kan fortfarande skapa pull request men du måste fixa alla konflikter för att slutföra sammanslagningen.
Tips
Även om den översätts underhålls fortfarande den ”senaste versionen <https://docs.qgis.org/latest>`_ av QGIS-dokumentationen och befintliga problem åtgärdas. Om du åtgärdar problem för en annan utgåva, ändra base från master till lämplig release_... gren i stegen ovan.
Beskriv din pull-begäran
En textruta öppnas: fyll i en rubrik och en relevant beskrivning av de ändringar du föreslår.
Om detta gäller en viss ”fråga <https://github.com/qgis/QGIS-Documentation/issues>`_, lägg till frågenumret i dina kommentarer. Detta görs genom att skriva # och numret på frågan (e.g. #1234). Om det föregås av termer som fix eller close, kommer den berörda frågan att stängas så snart som pull request är sammanslagen.
Lägg till länkar till alla dokumentationssidor som du ändrar.
Klicka på Create pull request.
Granska och kommentera pull request
Som framgår ovan kan vem som helst skicka in ändringar i dokumentationen via pull requests. På samma sätt kan vem som helst granska pull requests med frågor och kommentarer. Kanske stämmer inte skrivstilen överens med projektets riktlinjer, ändringen saknar några viktiga detaljer eller skärmdumpar, eller så kanske allt ser bra ut och är i sin ordning. Granskning hjälper till att förbättra kvaliteten på bidraget, både i form och innehåll.
För att granska en pull-begäran:
Navigera till sidan ”Pull requests” <https://github.com/qgis/QGIS-Documentation/pulls>`_ och klicka på den pull request som du vill kommentera.
Längst ner på sidan hittar du en textruta där du kan lämna allmänna kommentarer om pull request.
För att lägga till kommentarer om specifika rader,
Klicka på
och hitta den fil som du vill kommentera. Du kan behöva klicka på < > Display the source diff för att se ändringarna.Bläddra till den rad du vill kommentera och klicka på
. Då öppnas en textruta där du kan lämna en kommentar.
Specifika radkommentarer kan publiceras antingen:
som enskilda kommentarer med hjälp av knappen Lägg till en enskild kommentar. De publiceras allteftersom. Använd detta endast om du har få kommentarer att lägga till eller när du svarar på en annan kommentar.
eller som en del av en recension genom att trycka på knappen Starta en recension. Dina kommentarer skickas inte automatiskt efter validering, vilket gör att du kan redigera eller avbryta dem i efterhand, lägga till en sammanfattning av huvudpunkterna i granskningen eller globala instruktioner om pull-begäran och om du godkänner den eller inte. Detta är det praktiska sättet eftersom det är mer flexibelt och låter dig strukturera din granskning, redigera kommentarerna, publicera när du är redo och skicka en enda avisering till arkivets följare och inte en avisering för varje kommentar. Få mer information <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request>`_.
Fig. 1.10 Kommentera en rad med ett ändringsförslag
Radkommentarer kan bädda in förslag som skribenten av pull request kan tillämpa på pull request. För att lägga till ett förslag klickar du på knappen 
:sup:Insert a suggestion ovanför kommentarens textruta och ändrar texten i förslagsblocket.
Tips
Företräcker att skicka förslag till din pull request som en batch
Som författare till en pull request, när du direkt införlivar granskarnas feedback i din pull request, undvik att använda Commit suggestion-knappen längst ner i kommentaren när du har många förslag att ta itu med och föredrar att lägga till dem som en batch commit, det vill säga:
Byt till fliken
Tryck på Add suggestion to batch för varje omformulering som du vill inkludera. Du kommer att se en räknare som ökar allteftersom du går.
Tryck på någon av Commit suggestions-knapparna när du är redo att tillämpa förslagen på din pull request och ange ett meddelande som beskriver ändringarna.
Detta kommer att lägga till alla ändringar i din gren som en enda commit, vilket resulterar i en mer läsbar historik över ändringar och färre meddelanden för de som följer arkivet. Om du gör så här sparar du för övrigt också många klick.
Gör korrigeringar
En ny pull request kommer automatiskt att läggas till i Pull requests list. Andra redaktörer och administratörer kommer att granska din pull request och de kan komma med förslag eller be om korrigeringar.
En pull request kommer också att utlösa automatiska byggkontroller (t.ex. för rst-formatering, python-kodsyntaxer), och rapporter visas längst ner på sidan. Om ett fel hittas visas ett rött kors bredvid din commit. Klicka på det röda korset eller på Details i sammanfattningsavsnittet längst ner på pull request-sidan för att se detaljerna i felet. Du måste åtgärda alla rapporterade fel eller varningar innan dina ändringar överförs till qgis/QGIS-Documentation-arkivet.
Du kan göra ändringar i din pull request tills den har sammanfogats med huvudarkivet, antingen för att förbättra din request, för att åtgärda begärda ändringar eller för att åtgärda ett byggfel:
Klicka på fliken
på din pull request-sidaTryck på …-menyn till höger om det filnamn som du vill ändra och välj Edit file.
Filen öppnas i redigeringsläge; lägg till dina ändringar och bekräfta.
Eventuella ytterligare ändringar kommer automatiskt att läggas till i din pull request om du gör ändringarna i samma gren som du skickade in i din pull request. Av denna anledning bör du endast göra ytterligare ändringar om dessa ändringar avser det problem som du avser att åtgärda med denna pull request.
Om du vill åtgärda ett annat problem skapar du en ny gren för dessa ändringar och upprepar stegen ovan.
En administratör kommer att slå samman ditt bidrag efter att eventuella byggfel har rättats till och efter att du och administratörerna är nöjda med dina ändringar.
1.1.5. Ta bort din sammanslagna gren
Du kan ta bort grenen efter att dina ändringar har sammanfogats. Om du tar bort gamla grenar slipper du ha oanvända och föråldrade grenar i ditt repository.
Navigera till din förgrening av QGIS-Documentation-arkivet (
https://github.com/<YourName>/QGIS-Documentation).Klicka på fliken Branches. Under Dina grenar ser du en lista över dina grenar.
Klicka på ikonen
Delete this branch för att ta bort oönskade grenar.
1.2. Använda Gits kommandoradsverktyg
GitHubs webbgränssnitt är ett enkelt sätt att uppdatera QGIS-dokumentationsrepo med dina bidrag, men det erbjuder inte verktyg för att:
gruppera dina commits och rensa din ändringshistorik
åtgärda eventuella konflikter med huvudrepot
bygga dokumentationen för att testa dina ändringar
Du behöver installera git på din hårddisk för att få tillgång till mer avancerade och kraftfulla verktyg och ha en lokal kopia av förvaret. Några grundläggande saker som du ofta kan behöva beskrivs nedan. Du hittar också regler att ta hänsyn till även om du väljer webbgränssnittet.
I kodexemplen nedan visar rader som börjar med $ kommandon som du ska skriva medan # är kommentarer.
1.2.1. Lokal förvaringsplats
Nu är du redo att hämta en lokal klon av din QGIS-Documentation-arkiv.
Du kan klona ditt QGIS-arkiv med hjälp av webbadressen enligt följande:
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git
Den tidigare kommandoraden är bara ett exempel. Du bör anpassa både sökvägen och förvarets URL och ersätta <YourName> med ditt användarnamn på github.
Kontrollera följande:
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
origin är namnet på fjärrförvaret för ditt QGIS-Dokumentationsförvar.
master är huvudgrenen som används som standard. Du bör aldrig använda den för att bidra! Never!
Alternativt kan du klona ditt QGIS-arkiv med hjälp av SSH-protokollet:
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git
Tips
Fel på grund av nekad behörighet (publickey)?
Om du får felet Permission denied (publickey) med det förstnämnda kommandot kan det finnas ett problem med din SSH-nyckel. Se GitHub-hjälp för mer information.
Kontrollera följande om du använde SSH-protokollet:
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
Du kan börja arbeta här men i den långsiktiga processen kommer du att få många problem när du kommer att driva ditt bidrag (kallas Pull Request i github-processen) eftersom huvudgrenen i qgis / QGIS-Documentation-arkivet kommer att avvika från ditt lokala / avlägsna arkiv. Du måste då hålla reda på det huvudsakliga fjärrförvaret och arbeta med grenar.
1.2.2. Lägg till en annan fjärrförvaringsplats
För att kunna följa arbetet i huvudprojektet lägger du till ett nytt fjärrförvar i ditt lokala förvar. Detta nya fjärrarkiv är QGIS-Documentation-arkivet från QGIS-projektet:
$ git remote add upstream https://github.com/qgis/QGIS-Documentation.git
$ git remote -v
origin https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin https://github.com/<YourName>/QGIS-Documentation.git (push)
upstream https://github.com/qgis/QGIS-Documentation.git (fetch)
upstream https://github.com/qgis/QGIS-Documentation.git (push)
På samma sätt kan du använda SSH-protokollet för att lägga till ett fjärrarkiv i ditt lokala arkiv:
$ 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)
Så nu har du valet mellan två fjärrförvar:
origin för att lägga in din lokala gren i ditt fjärrarkiv
upstream för att sammanfoga (om du har rätt att göra det) ditt bidrag till det officiella ELLER för att uppdatera din mastergren av det lokala arkivet från mastergrenen av det officiella arkivet.
Observera
upstream är bara en etikett, ett slags standardnamn, men du kan kalla det vad du vill.
1.2.3. Uppdatera din basgren
Innan du arbetar med ett nytt bidrag bör du alltid uppdatera din huvudgren i ditt lokala arkiv. Förutsatt att du är villig att göra ändringar i testdokumentationen kör du följande kommandorader:
# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the 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 (aka <YourName>/QGIS-Documentation)
$ git push origin master
Nu har du dina lokala och avlägsna arkiv som båda har sin master-gren uppdaterad med den officiella master-grenen av QGIS-Documentation. Du kan börja arbeta på ditt bidrag.
Observera
Byt gren om du vill bidra till ett publicerat dokument
Tillsammans med testdokumentationen fortsätter vi att åtgärda problem i den senaste utgåvan, vilket innebär att du också kan bidra till den. Följ exempelkoden i föregående avsnitt och ersätt master med motsvarande gren i den senaste dokumentationen.
1.2.4. Bidra till din produktionsgren
Nu när din basgren är uppdaterad måste du skapa en dedikerad gren där du lägger till ditt bidrag. Arbeta alltid på en annan gren än basgrenen! Alltid!
# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit
Några ord om commit/push-kommandon:
försöka att bara göra ett bidrag (atomic change), dvs. bara ta itu med en enda fråga
försök att noggrant förklara vad du ändrar i titeln på din commit och i beskrivningen. Den första raden är en titel och ska börja med en versal bokstav och vara 80 tecken lång, avsluta inte med en
.. Var kortfattad. Din beskrivning kan vara längre, avsluta med en.och du kan ge mycket mer detaljer.använd
#med ett nummer för att hänvisa till ett problem. Prefix medFixom du fixar ärendet: din commit kommer att stänga ärendet.
Nu när dina ändringar har sparats och överförts till din lokala gren måste du skicka dem till ditt fjärrarkiv för att skapa en pull-begäran:
$ git push origin myNewBranch
1.2.6. Städa upp ditt lokala arkiv och fjärrarkivet
När din PR har slagits samman till den officiella QGIS-dokumentationen kan du ta bort din gren. Om du arbetar mycket på det här sättet kommer du inom några veckor att få en massa oanvändbara grenar. Så håll ditt arkiv rent på det här sättet:
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch
Och glöm inte att uppdatera master-grenen i ditt lokala arkiv!
1.3. Ytterligare läsning
Förutom webbgränssnittet Github och kommandoradsverktygen git som beskrivs ovan finns det också grafiska gränssnittsapplikationer som du kan använda för att skapa och hantera dina bidrag till dokumentationen.
När ändringarna i pull request står i konflikt med de senaste ändringarna som har skickats till målgrenen måste konflikterna lösas innan en sammanslagning är möjlig:
om konflikten gäller några få konkurrerande rader, finns en Resolve conflicts-knapp tillgänglig på GitHub pull request-sidan. Tryck på knappen och lös problemet enligt förklaringen i Lösning av en sammanslagningskonflikt på GitHub
om konflikten innebär att filer byter namn eller tas bort, måste du lösa konflikten med hjälp av git-kommandorader. Vanligtvis måste du först rebase din gren över målgrenen med hjälp av
git rebase targetBranch-anropet och fixa de konflikter som rapporteras. Läs mer på Lösa en sammanslagningskonflikt med hjälp av kommandoraden
Ibland, i slutet av korrekturläsningsprocessen, kan du hamna med ändringar som är uppdelade i flera commits som inte nödvändigtvis är värda det. Gits kommandorader hjälper dig att komprimera dessa commits till ett mindre antal och mer meningsfulla commit-meddelanden. Några detaljer på Using git rebase on the command line