Viktigt

Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.

3. Utvecklingsprocess

Som vanligt i projekt med öppen källkod är bidrag av kod och dokumentation till projektet mycket uppskattat. QGIS-gemenskapen är mycket stödjande. I det här avsnittet beskrivs proceduren för att utveckla och sammanfoga dina bidrag i QGIS-projektet.

3.1. Ett git-baserat projekt 

Komplexiteten i QGIS källkod har ökat avsevärt under de senaste åren. Därför är det svårt att förutse de bieffekter som tillägget av en funktion kommer att få. Tidigare hade QGIS-projektet mycket långa versionscykler eftersom det krävdes mycket arbete för att återställa programvarusystemets stabilitet efter att nya funktioner hade lagts till. För att lösa dessa problem övergick QGIS till en utvecklingsmodell som använder versionshanteringssystemet git: nya funktioner kodas först i bidragsgrenarna och slås samman till QGIS master (huvudgrenen) när de är färdiga och stabila.

QGIS källkod finns på https://github.com/qgis/QGIS.

3.1.1. Roller 

Det finns olika roller på GitHub. När du har ett konto på GitHub har du redan rätt att bidra genom att forka arkivet och har rollen ”contributor”. Kärnutvecklare är ”collaborators” och kan sammanfoga grenar till det uppströms och officiella arkivet.

3.1.2. Miljö 

För att komma igång med att använda och bidra till QGIS-arkivet behöver du:

ha ett GitHub-konto
skapa din egen kopia av QGIS-arkivet <https://github.com/qgis/QGIS>`_ (se fork)
har en git-klient installerad på ditt system
ställa in din git-miljö
och ha det så kul!

3.1.3. Installera git 

Git-projektet tillhandahåller de senaste versionerna av programvaran för de flesta plattformar. Följ instruktionerna på https://git-scm.com/downloads för att hämta och installera den kopia som motsvarar ditt operativsystem och din arkitektur. Där är det också möjligt att installera en git GUI-klient för att bläddra i och hantera dina arkiv (för det mesta kommer den att installera git om den ännu inte är tillgänglig).

3.2. Utveckling i filialer 

3.2.1. Bidrag till utveckling 

När du har registrerat dig på GitHub och har forkat repository kan du engagera dig som bidragsgivare.

Observera

Bidrag till QGIS-koden kan göras från ditt forked repository på GitHub-webbplatsen. Den nya koden kommer automatiskt att byggas av testmiljön. Men det här arbetsflödet kan snabbt avslöja sina gränser när du vill tillhandahålla komplexa ändringar. Instruktionerna nedan kommer att förutsätta en lokal klon.

Du kan bidra genom att initiera en pull request. Följ dessa generiska steg för att göra det:

Klona ditt arkiv till din lokala dator och konfigurera byggmiljön
Skapa en ny gren och gör redigeringarna för utveckling
Bekräfta dina ändringar och skicka tillbaka din gren till fjärrgaffeln på GitHub. En pull request erbjuds sedan som en webblänk (URL) direkt efteråt.
Öppna en pull request (PR) där du ber om att få dra commit(s) från din gren till master-grenen till uppströmsförvaret.
En granskningsprocess startas där andra bidragsgivare och samarbetspartners informeras om din pull request. Du bör reagera på deras kommentarer och förslag.

Observera

En mer detaljerad beskrivning av Githubs arbetsflöde för Fork & Pull finns på https://reflectoring.io/github-fork-and-pull/

Observera

De flesta av QGIS-projekten (webbplats, dokumentation, pyQGIS API, plugins …) finns tillgängliga på projektets GitHub-sida och kan få bidrag enligt samma process.

3.2.2. Tillgång till förvaret 

För att kunna interagera från din lokala disk med både din fjärranslutna fork och QGIS uppströmsarkiv, måste du:

Gör en klon av din kopia på din lokala disk

cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

Anslut QGIS huvudförvar (vi kallar det upstream) till ditt

git remote add upstream https://github.com/qgis/QGIS.git

Kontrollera anslutna fjärrarkiv

git remote -v
# origin   https://github.com/<YourName>/QGIS.git (fetch)
# origin   https://github.com/<YourName>/QGIS.git (push)
# upstream https://github.com/qgis/QGIS.git (fetch)
# upstream https://github.com/qgis/QGIS.git (push)

Ditt onlinearkiv är nu tillgängligt från din lokala enhet och du kan interagera med det med hjälp av namnet origin. När du vill hämta ändringar från qgis/QGIS-förvaret använder du upstream.

Observera

I QGIS förvarar vi vår mest stabila kod i den aktuella versionsgrenen. grenen master innehåller kod för den så kallade ”instabila” versionsserien. Med jämna mellanrum förgrenar vi en utgåva från master och fortsätter sedan stabiliseringen och selektivt införlivande av nya funktioner i master.

Se filen INSTALL i källträdet för specifika instruktioner om hur du bygger utvecklingsversioner.

3.2.3. Procedur 

Första tillkännagivandet på e-postlistan eller issues repo:
Innan du börjar kan du göra ett meddelande på e-postlistan för utvecklare för att se om någon annan utvecklare redan arbetar med samma funktion. Du kan också nämna ditt intresse som en kommentar i problemrapporten om en sådan finns i repot. Om den nya funktionen kräver några ändringar i QGIS-arkitekturen behövs ett QGIS Enhancement Proposal (QEP).
Skapa en gren i ditt lokala arkiv:
Skapa en ny git-gren för utvecklingen av den nya funktionen, baserat på det senaste tillståndet för master-grenen.
git fetch upstream master git checkout -b newfeature upstream/master
Nu kan du börja utveckla:
Koda dina ändringar på din lokala disk med din vanliga IDE. Kom ihåg att skriva testsviter för dina ändringar, när det är lämpligt.
Korrekt formatering, stavningskontroll och kvalitetskontroll av kod
Korrekt formatering, stavningskontroll och kvalitetskontroll av kod hanteras från en git-krok före kommitering.

Detta kan automatiseras genom att köra:
pre-commit install
Skriptet för stavningskontroll kan också köras ensamt med:
./scripts/astyle_all.sh
Bekräfta dina ändringar till git-repo:
När du gör en commit, skriv en beskrivande kommentar och gör hellre flera små commits om ändringarna i ett antal filer inte är relaterade till varandra. Omvänt föredrar vi att du grupperar relaterade ändringar i en enda commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
Utan alternativet -m öppnas ett nytt redigeringsfönster där du kan skriva ditt commit-meddelande.

här är några rekommendationer <https://www.conventionalcommits.org/en/v1.0.0/#summary>`_ om formatet för beskrivningar av åtaganden.
Nu kanske du vill dela med dig av ditt arbete till medlemmarna i QGIS community. Lägg upp din nya funktion i ditt online fork-repository genom att göra så här:
```
git push origin newfeature
```
Observera

Om grenen redan finns kommer dina ändringar att flyttas till den, annars skapas den.
Lämna in dina ändringar med en pull-request
När du öppnar pull-request utlöses den automatiska testsviten och kontrollerar om dina ändringar följer QGIS kodningsriktlinjer och inte bryter någon befintlig funktion. Du måste åtgärda eventuella rapporterade problem innan din gren slås samman uppströms.

Tips

Vi använder GitHub-åtgärder för att hantera de tester som ska köras på förvaret. För enkelhetens skull kan du aktivera åtgärderna i ditt arkiv så att testerna körs när du skickar in ändringarna. Du öppnar sedan pull-begäran efter att alla tester har godkänts, vilket gör granskningsprocessen mer effektiv.
Ombasera till uppströms master regelbundet:
Det är rekommenderat att regelbundet göra en rebase för att införliva ändringarna i master i grenen. Detta gör det lättare att senare sammanfoga grenen tillbaka till master. Efter en rebase måste du git push -f till ditt förgrenade repo.
git pull --rebase upstream master git push -f origin newfeature

Observera

Se följande webbplatser för information om hur du blir en GIT-master.

3.2.4. Testning innan sammanslagning tillbaka till master 

När du är klar med den nya funktionen och nöjd med stabiliteten, gör du ett tillkännagivande på utvecklarlistan. Innan ändringarna slås samman igen kommer de att testas av utvecklare och användare.

3.3. Skicka in Pull Requests 

Det finns några riktlinjer som hjälper dig att få in dina patchar och pull requests i QGIS på ett enkelt sätt, och som hjälper oss att hantera de patchar som skickas till oss på ett enkelt sätt.

I allmänhet är det enklare för utvecklare om du skickar in GitHub pull requests. Vi beskriver inte Pull Requests här, utan hänvisar dig till dokumentationen för Pull Requests på GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_.

Om du gör en pull request ber vi dig att regelbundet sammanfoga master till din PR-gren så att din PR alltid kan sammanfogas med uppströms master-gren.

Pull requests kommer att leda till att olika kontroller av Continuous Integration (CI)-systemet körs: bygga för olika miljöer och köra tester, köra code linters, stavningskontroller osv. Se till att titta på resultaten av dessa kontroller och försök att ta itu med de problem som de ger upphov till. Naturligtvis kan du ställa en fråga i pull request om du behöver hjälp från andra utvecklare för att förstå och/eller lösa ett problem.

Om du är utvecklare och vill utvärdera pull request-kön finns det ett mycket bra verktyg som låter dig göra detta från kommandoraden <https://changelog.com/posts/git-pulls-command-line-tool-for-github-pull-requests>`_

När du skickar in en PR bör du i allmänhet ta ansvar för att följa upp den till slutet - svara på frågor från andra utvecklare, leta upp en ”förkämpe” för din funktion och ge dem en mild påminnelse ibland om du ser att din PR inte åtgärdas. Tänk på att QGIS-projektet drivs av frivilliga krafter och att människor kanske inte kan ta hand om din PR omedelbart. Vi skannar de inkommande pull requests men ibland missar vi saker. Bli inte förolämpad eller orolig. Försök att identifiera en utvecklare som kan hjälpa dig och kontakta dem och fråga om de kan titta på din patch. Om du känner att din PR inte får den uppmärksamhet den förtjänar har du flera alternativ för att påskynda den (i prioritetsordning):

Hjälp till att granska andras pull requests för att frigöra den person som tilldelats din.
Skicka ett meddelande till e-postlistan för att ”marknadsföra” din PR och berätta hur bra det skulle vara att få den inkluderad i kodbasen.
Skicka ett meddelande till den person som din PR har tilldelats i PR-kön.
Skicka ett meddelande till projektets styrgrupp och be dem hjälpa till att se till att din PR införlivas i kodbasen.

3.3.1. Bästa praxis för att skapa en pull-begäran 

Starta alltid en feature-gren från nuvarande master.
Om du kodar en feature-gren ska du inte ”merga” något till den grenen, utan istället rebase enligt beskrivningen i nästa punkt för att hålla din historik ren.
Innan du skapar en pull request gör du git fetch upstream och git rebase upstream/master (givet att upstream är fjärrkontrollen för qgis-användaren och inte din egen fjärrkontroll, kontrollera din .git/config eller gör git remote -v | grep github.com/qgis).
Du kan göra en git rebase som i den sista raden upprepade gånger utan att göra någon skada (så länge som det enda syftet med din gren är att bli sammanslagen till master).
Uppmärksamhet: Efter en rebase måste du git push -f till din forked repo. KÄRNUTVECKLARE: GÖR INTE DETTA PÅ QGIS OFFENTLIGA ARKIV!

3.3.2. Särskilda etiketter för att meddela dokumentatörer 

Det finns en speciell etikett (Behövs dokumentation) som kan tilldelas av granskare till din pull request för att automatiskt generera problemrapporter i QGIS-Documentation repository så snart din pull request slås samman. Kom ihåg att nämna om din funktion förtjänar en sådan etikett.

Dessutom kan du lägga till speciella taggar i dina commit-meddelanden för att ge mer information till dokumentatörer. Commit-meddelandet läggs sedan till i den genererade problemrapporten:

[needs-docs] för att instruera dokumentskribenter att lägga till lite extra dokumentation efter en fix eller ett tillägg till en redan befintlig funktion.
[feature] när det gäller ny funktionalitet. Att fylla i en bra beskrivning i din PR är en bra början.

Snälla utvecklare använd dessa etiketter (skiftlägesokänsliga) så att dokumentförfattare har frågor att arbeta med och har en översikt över saker att göra. MEN ta dig också tid att lägga till lite text: antingen i commit eller i själva dokumenten.

3.3.3. Due Diligence 

QGIS är licensierat under GPL. Du bör göra allt du kan för att se till att du bara skickar in korrigeringar som inte är belastade av motstridiga immateriella rättigheter. Skicka inte heller in kod som du inte är glad över att ha gjort tillgänglig under GPL.

3.4. Kriterier för sammanslagning av Pull Requests 

Se QEP 323 - Policyer för inlämning av ändringar och sammanslagningar för aktuella policyer för acceptabel inlämning av pull-begäranden.

3.5. Få skrivåtkomst till GIT 

Skriftlig tillgång till QGIS källträd sker genom inbjudan. Vanligtvis när en person skickar in flera (det finns inget fast antal här) väsentliga patchar som visar grundläggande kompetens och förståelse för C++ och QGIS kodningskonventioner, kan en av PSC-medlemmarna eller andra befintliga utvecklare nominera den personen till PSC för beviljande av skrivåtkomst. Den som nominerar bör ge en grundläggande beskrivning av varför de anser att personen bör få skrivåtkomst. I vissa fall kommer vi att bevilja skrivåtkomst till personer som inte är C++-utvecklare, t.ex. översättare och dokumentatörer. I dessa fall ska personen fortfarande ha visat förmåga att skicka in patchar och helst ha skickat in flera betydande patchar som visar deras förståelse för att modifiera kodbasen utan att bryta saker, etc.

Observera

Sedan vi gick över till GIT är det mindre troligt att vi beviljar skrivåtkomst till nya utvecklare eftersom det är trivialt att dela kod inom github genom att forka QGIS och sedan utfärda pull requests.

Kontrollera alltid att allt kompileras innan du gör några commits / pull requests. Försök att vara medveten om eventuella avbrott som dina commits kan orsaka för personer som bygger på andra plattformar och med äldre / nyare versioner av bibliotek.