This section explains how the community can contribute code to Django via pull\nrequests. If you’re interested in how mergers handle\nthem, see Hantering av pull requests.
\nNedan 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.
\nDu kan också ladda upp en traditionell patch till Trac, men det är mindre praktiskt för recensioner.
\nDjango använder Git för sin källkontroll. Du kan ladda ner Git, men det är ofta enklare att installera med ditt operativsystems pakethanterare.
\nDjangos Git repository finns på GitHub, och det rekommenderas att du också arbetar med GitHub.
\nNär du har installerat Git är det första du ska göra att ange ditt namn och din e-postadress:
\n$ git config --global user.name "Your Real Name"\n$ git config --global user.email "you@email.com"\nObservera 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.
När du har skapat ditt GitHub-konto, med nick ”GitHub_nick”, och forkat Djangos arkiv, skapar du en lokal kopia av din fork:
\ngit clone https://github.com/GitHub_nick/django.git\nDetta 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:
\ncd django\nDitt GitHub-arkiv kommer att kallas ”origin” i Git.
\nDu 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\ngit fetch upstream\nDu kan t.ex. lägga till andra fjärrkontroller på samma sätt:
\ngit remote add akaariai https://github.com/akaariai/django.git\nNä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\nFlaggan -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.
\nOm du istället arbetade för en fix på 1.4-grenen skulle du göra det:
\ngit checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x\nAnta att arbetet utförs på filialen ticket_xxxxx. Gör några ändringar och bekräfta dem:
\ngit commit\nNä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.
\nOm du behöver göra ytterligare arbete på din gren, commit så ofta som nödvändigt:
\ngit commit -m 'Added two more tests for edge cases.'\nDu kan publicera ditt arbete på GitHub genom att köra:
\ngit push origin ticket_xxxxx\nNär du går till din GitHub-sida kommer du att se att en ny gren har skapats.
\nOm 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.
\nObservera 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:
\ncommits with one logical change in each, following the\ncoding style,
välformade meddelanden för varje commit: en sammanfattande rad och sedan stycken om 72 tecken därefter – se 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.
\nNär du har skapat din pull request bör du lägga till en kommentar i det relaterade Trac-ärendet 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”.
\nPull 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.
\nTo change the message of the most recent commit, run:
\ngit commit --amend\nThis opens an editor with the current commit message. Edit it, save, and close\nto update the commit.
\nTo change the message of an earlier commit, use the ”reword” option in\ninteractive rebase. For example, to reword one of the last three commits:
\ngit rebase -i HEAD~3\nThis opens an editor listing the three commits, each prefixed with the word\n”pick”. Change ”pick” to ”reword” (or ”r”) on the line of the commit you want\nto change, then save and close. A new editor will open for each commit marked\nas ”reword”, allowing you to update the message.
\nSee Riktlinjer för åtaganden for the required commit message format.
\nAfter rewriting a commit that has already been pushed to GitHub, you will need\nto force-push your branch:
\ngit push --force-with-lease origin ticket_xxxxx\nIn the example above, you created two commits, the ”Fixed #xxxxx – …”\ncommit and the ”Added two more tests …” commit.
\nVi 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.
\nOm du vill omarbeta historiken för din gren kan du pressa ihop överföringarna till en enda genom att använda interaktiv rebase:
\ngit rebase -i HEAD~2\nHEAD~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.
\nÄ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.
\nDu 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:
\ngit rebase -i HEAD~3\n# Choose edit, pick, pick for the commits\n# Now you are able to rework the commit (use git add normally to add changes)\n# When finished, commit work with "--amend" and continue\ngit commit --amend\n# Reword the commit message if needed\ngit rebase --continue\n# The second and third commits should be applied.\nOm 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:
\ngit push --force-with-lease origin ticket_xxxxx\nObservera 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.
\nNär uppströms (django/django) har ändrats bör du ombasera ditt arbete. För att göra detta, använd:
git fetch upstream\ngit rebase upstream/main\nArbetet 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.
\nOm 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.
\nAnledningen 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.
\nDet ä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.
\nGö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:
\ngit rebase -i HEAD~2\nPressa in den andra commiten i den första. Skriv ett commit-meddelande i stil med:
\nMade changes asked in review by <reviewer>.\n\n- Fixed whitespace errors in foobar.\n- Reworded the docstring of bar().\nSlutligen, 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:
\ngit push origin ticket_xxxxx\nDin pull request bör nu också innehålla den nya commit.
\nObservera att sammanslagningen sannolikt kommer att pressa in granskningsöverföringen i den föregående överföringen när koden överförs.
\nEtt 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:
\ngit checkout -b pull_xxxxx upstream/main\ncurl -L https://github.com/django/django/pull/xxxxx.patch | git am\nDetta 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.
\nFör mer information om hur du arbetar med pull requests, se riktlinjer för sammanslagningar.
\nArbeta på GitHub om du kan.
Meddela ditt arbete på Trac-ärendet 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.