Är du intresserad av att ge tillbaka lite till gemenskapen? Kanske har du hittat en bugg i Django som du skulle vilja se fixad, eller kanske finns det en liten funktion som du vill lägga till (men kom ihåg att förslag på nya funktioner ska följa processen för att föreslå nya funktioner).
\nAtt bidra till Django själv är det bästa sättet att se dina egna problem hanteras. Det kan verka skrämmande i början, men det är en väl upptrampad väg med dokumentation, verktyg och en gemenskap som stöder dig. Vi guidar dig genom hela processen, så att du kan lära dig genom exempel.
\nFör denna handledning förväntar vi oss att du har åtminstone en grundläggande förståelse för hur Django fungerar. Detta innebär att du bör vara bekväm med att gå igenom de befintliga handledningarna om skriva din första Django-app. Dessutom bör du ha en god förståelse för Python självt. Men om du inte gör det är Dive Into Python en fantastisk (och gratis) onlinebok för nybörjare i Python-programmering.
\nDe av er som inte är bekanta med versionshanteringssystem och Trac kommer att upptäcka att denna handledning och dess länkar innehåller tillräckligt med information för att komma igång. Men du kommer förmodligen att vilja läsa lite mer om dessa olika verktyg om du planerar att bidra till Django regelbundet.
\nFör det mesta försöker denna handledning dock förklara så mycket som möjligt, så att den kan vara till nytta för den bredaste publiken.
\n\nVi kommer att gå igenom hur du bidrar till Django för första gången. I slutet av denna handledning bör du ha en grundläggande förståelse för både verktygen och de processer som är inblandade. Specifikt kommer vi att täcka följande:
\nInstallera Git.
Nedladdning av en kopia av Djangos utvecklingsversion.
Kör Djangos testsvit.
Skriva ett test för dina ändringar.
Skriva koden för dina ändringar.
Testa dina ändringar.
Skicka in en pull-begäran.
Var du kan söka efter mer information.
När du är klar med handledningen kan du titta igenom resten av Djangos dokumentation om att bidra. Den innehåller massor av bra information och är ett måste för alla som vill bli en regelbunden bidragsgivare till Django. Om du har frågor har den förmodligen svaren.
\n\n\nSom bidragsgivare kan du hjälpa oss att hålla Django-gemenskapen öppen och inkluderande. Läs och följ vår Uppförandekod.
\nFör den här handledningen behöver du ha Git installerat för att ladda ner den aktuella utvecklingsversionen av Django och för att generera en gren för de ändringar du gör.
\nFör att kontrollera om du har Git installerat skriver du git på kommandoraden. Om du får meddelanden som säger att kommandot inte kunde hittas måste du ladda ner och installera det, se `Gits nedladdningssida`__.
Om du inte är så bekant med Git kan du alltid ta reda på mer om dess kommandon (när det väl är installerat) genom att skriva git help på kommandoraden.
Det första steget för att bidra till Django är att få en kopia av källkoden. Först, fork Django på GitHub. Använd sedan kommandot cd från kommandoraden för att navigera till den katalog där du vill att din lokala kopia av Django ska finnas.
Ladda ner Djangos källkodsarkiv med hjälp av följande kommando:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nNu när du har en lokal kopia av Django kan du installera det precis som du skulle installera vilket paket som helst med hjälp av pip. Det bekvämaste sättet att göra det är att använda en virtuell miljö, som är en funktion inbyggd i Python som gör att du kan hålla en separat katalog med installerade paket för vart och ett av dina projekt så att de inte stör varandra.
Det är en bra idé att samla alla virtuella miljöer på ett ställe, t.ex. i .virtualenvs/ i din hemkatalog.
Skapa en ny virtuell miljö genom att köra:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nSökvägen är den plats där den nya miljön kommer att sparas på din dator.
\nDet sista steget i konfigurationen av din virtuella miljö är att aktivera den:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nOm kommandot källa inte är tillgängligt kan du försöka använda en punkt istället:
$ . ~/.virtualenvs/djangodev/bin/activate\nDu måste aktivera den virtuella miljön varje gång du öppnar ett nytt terminalfönster.
\n\nNamnet på den virtuella miljö som för närvarande är aktiverad visas på kommandoraden för att hjälpa dig att hålla reda på vilken du använder. Allt som du installerar via pip medan det här namnet visas kommer att installeras i den virtuella miljön, isolerat från andra miljöer och systemomfattande paket.
Gå vidare och installera den tidigare klonade kopian av Django:
\nLinux / macOS
$ python -m pip install -e /path/to/your/local/clone/django/\nWindows
...\\> py -m pip install -e \\path\\to\\your\\local\\clone\\django\\\nDen installerade versionen av Django pekar nu på din lokala kopia genom att installera i redigerbart läge. Du kommer omedelbart att se alla ändringar du gör i den, vilket är till stor hjälp när du testar ditt första bidrag.
\nNär du bidrar till Django är det mycket viktigt att dina kodändringar inte introducerar buggar i andra delar av Django. Ett sätt att kontrollera att Django fortfarande fungerar efter att du har gjort dina ändringar är att köra Djangos testsvit. Om alla tester fortfarande godkänns kan du vara ganska säker på att dina ändringar fungerar och inte har förstört andra delar av Django. Om du aldrig har kört Djangos testsvit tidigare är det en bra idé att köra den en gång i förväg för att bekanta dig med dess resultat.
\nInnan du kör testsviten ska du ange Djangos katalog tests/ med kommandot cd tests och installera testberoenden genom att köra:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nOm du stöter på ett fel under installationen kan det hända att ditt system saknar ett beroende för ett eller flera av Python-paketen. Läs dokumentationen för det paket som inte fungerar eller sök på webben efter det felmeddelande som du stöter på.
\nNu är vi redo att köra testsviten:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nNu kan du luta dig tillbaka och slappna av. Djangos hela testsvit har tusentals tester och det tar minst några minuter att köra, beroende på hastigheten på din dator.
\nNär Djangos testsvit körs kommer du att se en ström av tecken som representerar statusen för varje test när det slutförs. E indikerar att ett fel uppstod under ett test och F indikerar att ett tests påståenden misslyckades. Båda dessa anses vara testfel. Samtidigt indikerar x och s förväntade misslyckanden respektive överhoppade tester. Punkter indikerar godkända tester.
Överhoppade tester beror vanligtvis på att det saknas externa bibliotek som krävs för att köra testet; se Kör alla tester för en lista över beroenden och se till att installera alla för tester som är relaterade till de ändringar du gör (vi behöver inte några för den här handledningen). Vissa tester är specifika för en viss databasbackend och kommer att hoppas över om du inte testar med den backend. SQLite är databasens backend för standardinställningarna. För att köra testerna med en annan backend, se Använda en annan settings-modul.
\nNär testerna har slutförts bör du mötas av ett meddelande som informerar dig om testsviten klarade sig eller inte. Eftersom du ännu inte har gjort några ändringar i Djangos kod bör hela testsviten bli godkänd. Om du får misslyckanden eller fel, se till att du har följt alla tidigare steg korrekt. Se Kör enhetstesterna för mer information.
\nObservera att den senaste Django-grenen ”main” kanske inte alltid är stabil. När du utvecklar mot ”main” kan du kontrollera `Djangos continuous integration builds`__ för att avgöra om felen är specifika för din maskin eller om de också finns i Djangos officiella builds. Om du klickar för att visa ett visst bygge kan du visa ”Configuration Matrix” som visar fel uppdelade efter Python-version och databasbackend.
\n\nFör denna handledning kommer vi att arbeta med en ”falskt accepterat ärendet” som en fallstudie. Här är de imaginära detaljerna:
\n\nVi kommer nu att implementera denna funktion och tillhörande tester.
\nInnan du gör några ändringar ska du skapa en ny gren för ärendet:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nDu kan välja vilket namn du vill för grenen, ”ticket_99999” är ett exempel. Alla ändringar som görs i den här grenen kommer att vara specifika för ärendet och kommer inte att påverka huvudkopian av koden som vi klonade tidigare.
\nFör att ett bidrag ska accepteras i Django måste det i de flesta fall innehålla tester. För bidrag med buggfixar innebär detta att man skriver ett regressionstest för att säkerställa att buggen aldrig återinförs i Django senare. Ett regressionstest bör skrivas på ett sådant sätt att det misslyckas medan buggen fortfarande existerar och godkänns när buggen har åtgärdats. För bidrag som innehåller nya funktioner måste du inkludera tester som säkerställer att de nya funktionerna fungerar korrekt. Även de bör misslyckas när den nya funktionen inte finns, och sedan godkännas när den har implementerats.
\nEtt bra sätt att göra detta är att skriva de nya testerna först, innan du gör några ändringar i koden. Denna utvecklingsstil kallas ”testdriven utveckling” och kan tillämpas på både hela projekt och enstaka ändringar. När du har skrivit dina tester kör du dem sedan för att se till att de verkligen misslyckas (eftersom du inte har fixat den buggen eller lagt till den funktionen ännu). Om dina nya tester inte misslyckas måste du fixa dem så att de gör det. När allt kommer omkring är ett regressionstest som klarar sig oavsett om en bugg finns inte särskilt användbart för att förhindra att den buggen återkommer längre fram.
\nNu till vårt praktiska exempel.
\nFör att lösa detta ärende ska vi lägga till en make_toast()-funktion i modulen django.shortcuts. Först ska vi skriva ett test som försöker använda funktionen och kontrollera att dess utdata ser korrekt ut.
Navigera till Djangos mapp tests/shortcuts/ och skapa en ny fil test_make_toast.py. Lägg till följande kod:
from django.shortcuts import make_toast\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), "toast")\nDetta test kontrollerar att make_toast() returnerar 'toast'.
Eftersom vi inte har gjort några ändringar i django.shortcuts ännu, borde vårt test misslyckas. Låt oss köra alla tester i mappen shortcuts för att se till att det verkligen är vad som händer. cd till Django tests/ katalogen och kör:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nOm testerna kördes korrekt bör du se ett fel som motsvarar den testmetod vi lade till, med detta fel:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nOm alla tester godkändes bör du se till att du lägger till det nya testet som visas ovan i rätt mapp och filnamn.
\nNu ska vi lägga till funktionen make_toast().
Navigera till mappen django/ och öppna filen shortcuts.py. Längst ner lägger du till:
def make_toast():\n return "toast"\nNu måste vi se till att testet vi skrev tidigare godkänns, så att vi kan se om koden vi lagt till fungerar korrekt. Återigen, navigera till Django tests/ katalogen och kör:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nAllt ska godkännas. Om det inte gör det, kontrollera att du har lagt till funktionen i rätt fil.
\nNär du har verifierat att dina ändringar och ditt test fungerar korrekt är det en bra idé att köra hela Djangos testsvit för att verifiera att din ändring inte har infört några buggar i andra delar av Django. Att klara hela testsviten garanterar inte att din kod är buggfri, men det hjälper till att identifiera många buggar och regressioner som annars kan gå obemärkt förbi.
\nFör att köra hela Djangos testsvit, cd till Djangos tests/ katalog och kör:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nDet här är en ny funktion, så den bör dokumenteras. Öppna filen docs/topics/http/shortcuts.txt och lägg till följande i slutet av filen:
``make_toast()``\n================\n\n.. function:: make_toast()\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nEftersom den här nya funktionen kommer att finnas med i en kommande version läggs den också till i versionsinformation för nästa version av Django. Öppna versionsinformation för den senaste versionen i docs/releases/, som i skrivande stund är 2.2.txt. Lägg till en anteckning under rubriken ”Minor Features”:
:mod:`django.shortcuts`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nFör mer information om hur du skriver dokumentation, inklusive en förklaring av vad versionadded handlar om, se Skriva dokumentation. Den sidan innehåller också en förklaring av hur man bygger en kopia av dokumentationen lokalt, så att du kan förhandsgranska den HTML som kommer att genereras.
Nu är det dags att granska de ändringar som gjorts i grenen. För att visa alla ändringar som är klara för commit, kör:
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\nVisa sedan skillnaderna mellan din nuvarande kopia av Django (med dina ändringar) och den revision som du ursprungligen checkade ut tidigare i handledningen med:
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nAnvänd piltangenterna för att flytta uppåt och nedåt.
\ndiff --git a/django/shortcuts.py b/django/shortcuts.py\nindex 7ab1df0e9d..8dde9e28d9 100644\n--- a/django/shortcuts.py\n+++ b/django/shortcuts.py\n@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):\n\n # Finally, fall back and assume it's a URL\n return to\n+\n+\n+def make_toast():\n+ return 'toast'\ndiff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\n Minor features\n --------------\n\n+:mod:`django.shortcuts`\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\n+\n :mod:`django.contrib.admin`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ndiff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt\nindex 7b3a3a2c00..711bf6bb6d 100644\n--- a/docs/topics/http/shortcuts.txt\n+++ b/docs/topics/http/shortcuts.txt\n@@ -271,3 +271,12 @@ This example is equivalent to::\n my_objects = list(MyModel.objects.filter(published=True))\n if not my_objects:\n raise Http404("No MyModel matches the given query.")\n+\n+``make_toast()``\n+================\n+\n+.. function:: make_toast()\n+\n+.. versionadded:: 2.2\n+\n+Returns ``'toast'``.\ndiff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py\nnew file mode 100644\nindex 0000000000..6f4c627b6e\n--- /dev/null\n+++ b/tests/shortcuts/test_make_toast.py\n@@ -0,0 +1,7 @@\n+from django.shortcuts import make_toast\n+from django.test import SimpleTestCase\n+\n+\n+class MakeToastTests(SimpleTestCase):\n+ def test_make_toast(self):\n+ self.assertEqual(make_toast(), 'toast')\nNär du är klar med förhandsgranskningen av ändringarna trycker du på tangenten ”q” för att återgå till kommandoraden. Om diffen såg okej ut är det dags att överföra ändringarna.
\nFör att bekräfta ändringarna:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nDetta öppnar en textredigerare för att skriva commit-meddelandet. Följ riktlinjerna för commit-meddelanden och skriv ett meddelande som:
\nFixed #99999 -- Added a shortcut function to make toast.\nNär du har bekräftat ändringarna skickar du den till din fork på GitHub (ersätt ”ticket_99999” med namnet på din gren om det är annorlunda):
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nDu kan skapa en pull request genom att besöka Django GitHub-sidan. Du kommer att se din gren under ”Your recently pushed branches”. Klicka på ”Compare & pull request” bredvid den.
\nGör det inte för den här handledningen, men på nästa sida som visar en förhandsgranskning av ändringarna klickar du på ”Skapa pull request”.
\nGrattis, du har lärt dig hur man gör en pull request till Django! Detaljer om mer avancerade tekniker som du kan behöva finns i Arbeta med Git och GitHub.
\nNu kan du använda dessa kunskaper på ett bra sätt genom att hjälpa till att förbättra Djangos kodbas.
\nInnan du går in för att bidra till Django finns det lite mer information om att bidra som du förmodligen bör ta en titt på:
\nDu bör se till att läsa Djangos dokumentation om claiming tickets and submitting pull requests. Den täcker Trac-etikett, hur du gör anspråk på ärenden för dig själv, förväntad kodningsstil (både för kod och dokument) och många andra viktiga detaljer.
Förstagångsbidragstagare bör också läsa Djangos dokumentation för förstagångsbidragstagare. Den innehåller många goda råd för oss som är nya när det gäller att hjälpa till med Django.
Efter detta, om du fortfarande är hungrig efter mer information om att bidra, kan du alltid bläddra igenom resten av Djangos dokumentation om att bidra. Den innehåller massor av användbar information och bör vara din första källa för att svara på eventuella frågor du kan ha.
När du har gått igenom en del av den informationen är du redo att gå ut och hitta ett eget ärende att bidra till. Var särskilt uppmärksam på ärenden med kriteriet ”lättplockat”. Dessa ärenden är ofta mycket enklare till sin natur och passar bra för förstagångsbidragstagare. När du är bekant med att bidra till Django kan du börja arbeta med svårare och mer komplicerade ärenden.
\nOm du bara vill komma igång redan nu (och ingen skulle klandra dig!), försök att ta en titt på listan över `enkla ärenden utan gren`__ och `enkla ärenden som har grenar som behöver förbättras`__. Om du är bekant med att skriva tester kan du också titta på listan över ”enkla ärenden som behöver tester”. Kom ihåg att följa riktlinjerna om att göra anspråk på ärenden som nämndes i länken till Djangos dokumentation på claiming tickets and submitting branches.
\nNär ett ärende har en gren måste det granskas av en andra uppsättning ögon. När du har skickat in en pull request ska du uppdatera metadata för ärendet genom att ställa in flaggorna på ärendet så att det står ”har patch”, ”behöver inte tester” etc. så att andra kan hitta det för granskning. Att bidra behöver inte nödvändigtvis alltid innebära att skriva kod från grunden. Att granska öppna pull requests är också ett mycket användbart bidrag. Se Bedömning av ärenden för detaljer.
\n