Arbeta med Git och GitHub

Detta avsnitt förklarar hur samhället kan bidra med kod till Django via pull requests. Om du är intresserad av hur :ref:``mergers <mergers-team>` hanterar dem, se Bekräftelse av kod.

Nedan kommer vi att visa hur man skapar en GitHub pull request som innehåller ändringarna för Trac ticket #xxxxx. Genom att skapa en helt färdig pull request kommer du att göra granskarens jobb enklare, vilket innebär att ditt arbete är mer sannolikt att slås samman till Django.

Du kan också ladda upp en traditionell patch till Trac, men det är mindre praktiskt för recensioner.

Installera Git

Django använder Git för sin källkontroll. Du kan ladda ner Git, men det är ofta enklare att installera med ditt operativsystems pakethanterare.

Djangos Git repository finns på GitHub, och det rekommenderas att du också arbetar med GitHub.

När du har installerat Git är det första du ska göra att ange ditt namn och din e-postadress:

$ git config --global user.name "Your Real Name"
$ git config --global user.email "[e-mail]"

Observera att user.name ska vara ditt riktiga namn, inte ditt GitHub-nick. GitHub bör känna till den e-postadress du använder i fältet user.email, eftersom detta kommer att användas för att associera dina åtaganden med ditt GitHub-konto.

Konfigurera lokalt arkiv

När du har skapat ditt GitHub-konto, med nick ”GitHub_nick”, och forkat Djangos arkiv, skapar du en lokal kopia av din fork:

git clone https://github.com/GitHub_nick/django.git

Detta kommer att skapa en ny katalog ”django”, som innehåller en klon av ditt GitHub-arkiv. Resten av git-kommandona på den här sidan måste köras i den klonade katalogen, så byt till den nu:

cd django

Ditt GitHub-arkiv kommer att kallas ”origin” i Git.

Du bör också ställa in django/django som en ”uppströms” fjärrkontroll (det vill säga, berätta för git att referens Django-förvaret var källan till din förgrening av det):

git remote add upstream https://github.com/django/django.git
git fetch upstream

Du kan t.ex. lägga till andra fjärrkontroller på samma sätt:

git remote add akaariai https://github.com/akaariai/django.git

Arbeta på en biljett

När du arbetar med ett ärende ska du skapa en ny gren för arbetet och basera det arbetet på upstream/main:

git checkout -b ticket_xxxxx upstream/main

Flaggan -b skapar en ny gren åt dig lokalt. Tveka inte att skapa nya grenar även för de minsta sakerna - det är vad de är till för.

Om du istället arbetade för en fix på 1.4-grenen skulle du göra det:

git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x

Anta att arbetet utförs på filialen ticket_xxxxx. Gör några ändringar och bekräfta dem:

git commit

När du skriver commit-meddelandet, följ riktlinjerna för commit-meddelanden för att underlätta arbetet med sammanslagningen. Om du är obekväm med engelska, försök åtminstone att beskriva exakt vad commit gör.

Om du behöver göra ytterligare arbete på din gren, commit så ofta som nödvändigt:

git commit -m 'Added two more tests for edge cases'

Publiceringsarbete

Du kan publicera ditt arbete på GitHub genom att köra:

git push origin ticket_xxxxx

När du går till din GitHub-sida kommer du att se att en ny gren har skapats.

Om du arbetar på ett Trac-ärende bör du nämna i ärendet att ditt arbete är tillgängligt från filial ticket_xxxxx i ditt GitHub-repo. Inkludera en länk till din filial.

Observera att ovanstående gren kallas för en ”topic branch” i Git-språk. Det står dig fritt att skriva om historien för den här grenen, till exempel genom att använda git rebase. Andra människor bör inte basera sitt arbete på en sådan gren, eftersom deras klon skulle bli korrupt när du redigerar åtaganden.

Det finns också ”offentliga grenar”. Det här är grenar som andra människor ska forka, så historiken för dessa grenar bör aldrig ändras. Bra exempel på offentliga grenar är grenarna main och stable/A.B.x i django/django-förvaret.

När du tycker att ditt arbete är redo att dras in i Django bör du skapa en pull request på GitHub. En bra pull request innebär:

• commits med en logisk ändring i varje, enligt kodningsstil,

• välformade meddelanden för varje commit: en sammanfattande rad och sedan stycken om 72 tecken därefter – se :ref:committing guidelines <committing-guidelines> för mer information,

• dokumentation och tester, om det behövs – egentligen behövs alltid tester, förutom vid ändringar i dokumentationen.

Testsviten måste godkännas och dokumentationen måste byggas utan varningar.

När du har skapat din pull request bör du lägga till en kommentar i den relaterade Trac-biljetten där du förklarar vad du har gjort. I synnerhet bör du notera den miljö där du körde testerna, till exempel: ”alla tester godkänns under SQLite och MySQL”.

Pull requests på GitHub har bara två tillstånd: öppen och stängd. Den merger som kommer att hantera din pull request har bara två alternativ: att merga den eller stänga den. Av den anledningen är det inte användbart att göra en pull request förrän koden är redo för sammanfogning - eller tillräckligt nära för att en sammanfogare ska kunna avsluta den själv.

Ombasering av grenar

I exemplet ovan skapade du två commits, commiten ”Fixed ticket_xxxxx” och commiten ”Added two more tests”.

Vi vill inte ha hela historiken för din arbetsprocess i ditt repository. Din commit ”Lagt till ytterligare två tester” skulle vara ohjälpsamt brus. Istället vill vi hellre bara ha en commit som innehåller allt ditt arbete.

Om du vill omarbeta historiken för din gren kan du pressa ihop överföringarna till en enda genom att använda interaktiv rebase:

git rebase -i HEAD~2

HEAD~2 ovan är en förkortning för två senaste commits. Ovanstående kommando öppnar en editor som visar de två commits, med ordet ”pick” som prefix.

Ändra ”pick” på den andra raden till ”squash” istället. Detta kommer att behålla den första överföringen och pressa in den andra överföringen i den första. Spara och avsluta redigeringsverktyget. Ett andra redigeringsfönster öppnas, så att du kan omformulera meddelandet för commit för commit nu när det innehåller båda dina steg.

Du kan också använda alternativet ”edit” i rebase. På så sätt kan du ändra en enda commit, t.ex. för att rätta ett stavfel i en dokumentsträng:

git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.

Om din ämnesgren redan är publicerad på GitHub, t.ex. om du gör mindre ändringar för att ta hänsyn till en granskning, måste du force-pusha ändringarna:

git push -f origin ticket_xxxxx

Observera att detta kommer att skriva om historiken för ticket_xxxxx - om du kontrollerar commit-hasharna före och efter operationen på GitHub kommer du att märka att commit-hasharna inte matchar längre. Detta är acceptabelt eftersom grenen är en ämnesgren och ingen bör basera sitt arbete på den.

Efter att uppströms har förändrats

När uppströms (django/django) har ändrats bör du ombasera ditt arbete. För att göra detta, använd:

git fetch upstream
git rebase upstream/main

Arbetet ombaseras automatiskt med hjälp av den gren du förgrenade dig på, i exemplet med upstream/main.

Kommandot rebase tar tillfälligt bort alla dina lokala ändringar, tillämpar uppströmsändringarna och tillämpar sedan dina lokala ändringar igen på arbetet.

Om det finns sammanfogningskonflikter måste du lösa dem och sedan använda git rebase --continue. När som helst kan du använda git rebase --abort för att återgå till det ursprungliga tillståndet.

Observera att du vill basera på uppströms, inte sammanfoga uppströms.

Anledningen till detta är att genom ombasering kommer dina åtaganden alltid att vara * ovanpå* uppströms arbete, inte blandade med ändringarna i uppströms. På så sätt kommer din gren endast att innehålla kommandon som är relaterade till dess ämne, vilket gör det lättare att krossa.

Efter granskning

Det är ovanligt att få in någon icke-trivial mängd kod i kärnan utan ändringar som begärts av granskare. I det här fallet är det ofta en bra idé att lägga till ändringarna som en inkrementell commit till ditt arbete. Det gör att granskaren enkelt kan kontrollera vilka ändringar du har gjort.

Gör i så fall de ändringar som krävs av granskaren. Commit så ofta som nödvändigt. Innan du publicerar ändringarna ska du basa om ditt arbete. Om du lägger till två commits skulle du köra:

git rebase -i HEAD~2

Pressa in den andra commiten i den första. Skriv ett commit-meddelande i stil med:

Made changes asked in review by <reviewer>

- Fixed whitespace errors in foobar
- Reworded the docstring of bar()

Slutligen, tryck tillbaka ditt arbete till ditt GitHub-arkiv. Eftersom du inte rörde de offentliga commits under rebase bör du inte behöva force-push:

git push origin ticket_xxxxx

Din pull request bör nu också innehålla den nya commit.

Observera att sammanslagningen sannolikt kommer att pressa in granskningsöverföringen i den föregående överföringen när koden överförs.

Arbetar på en patch

Ett av sätten som utvecklare kan bidra till Django är genom att granska patchar. Dessa patchar kommer vanligtvis att finnas som pull requests på GitHub och kan enkelt integreras i ditt lokala repository:

git checkout -b pull_xxxxx upstream/main
curl -L https://github.com/django/django/pull/xxxxx.patch | git am

Detta kommer att skapa en ny gren och sedan tillämpa ändringarna från pull request på den. Nu kan du köra testerna eller göra något annat som du behöver göra för att undersöka kvaliteten på patchen.

För mer information om hur du arbetar med pull requests, se :ref:riktlinjer för sammanslagningar <handling-pull-requests>.

Översikt

• Arbeta på GitHub om du kan.

• Meddela ditt arbete på Trac-biljetten genom att länka till din GitHub-gren.

• När du har något klart kan du göra en pull request.

• Gör dina pull requests så bra som möjligt.

• När du gör korrigeringar av ditt arbete, använd git rebase -i för att krossa överföringarna.

• När uppströms har ändrats, gör git fetch upstream; git rebase.