Skriva ditt första bidrag till Django¶
Introduktion¶
Är du intresserad av att ge tillbaka lite till samhället? 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).
Att 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.
Vem är denna guide skriven för?¶
Se även
Om du letar efter en referens om detaljerna för att göra kodbidrag, se Bidra med kod dokumentation.
Fö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.
De 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.
Fö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.
Var du kan få hjälp:
Om du har problem med att gå igenom denna handledning, skicka ett meddelande på Django Forum eller titta in på Django Discord server för att chatta med andra Django-användare som kanske kan hjälpa till.
Vad omfattar denna handledning?¶
Vi 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:
Installera 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.
Python 3 krävs!
Den nuvarande versionen av Django stöder inte Python 2.7. Hämta Python 3 på Pythons nedladdningssida eller med ditt operativsystems pakethanterare.
För Windows-användare
Se Installera Python på Windows-dokumenten för ytterligare vägledning.
Uppförandekod¶
Som bidragsgivare kan du hjälpa oss att hålla Django-gemenskapen öppen och inkluderande. Läs och följ vår ”Uppförandekod” <https://www.djangoproject.com/conduct/>`_.
Installera Git¶
Fö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.
Fö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.
Skaffa en kopia av Djangos utvecklingsversion¶
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:
$ git clone https://github.com/YourGitHubName/django.git
...\> git clone https://github.com/YourGitHubName/django.git
Anslutning med låg bandbredd?
Du kan lägga till argumentet --djup 1 till git clone för att hoppa över att ladda ner hela Djangos commit-historik, vilket minskar dataöverföringen från ~250 MB till ~70 MB.
Nu 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:
$ python3 -m venv ~/.virtualenvs/djangodev
...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev
Sökvägen är den plats där den nya miljön kommer att sparas på din dator.
Det sista steget i konfigurationen av din virtuella miljö är att aktivera den:
$ source ~/.virtualenvs/djangodev/bin/activate
Om kommandot källa inte är tillgängligt kan du försöka använda en punkt istället:
$ . ~/.virtualenvs/djangodev/bin/activate
Du måste aktivera den virtuella miljön varje gång du öppnar ett nytt terminalfönster.
För Windows-användare
För att aktivera din virtuella miljö i Windows kör du:
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
Namnet 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:
$ python -m pip install -e /path/to/your/local/clone/django/
...\> py -m pip install -e \path\to\your\local\clone\django\
Den 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.
Kör Djangos testsvit för första gången¶
Nä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.
Innan du kör testsviten ska du ange Djangos katalog tests/ med kommandot cd tests och installera testberoenden genom att köra:
$ python -m pip install -r requirements/py3.txt
...\> py -m pip install -r requirements\py3.txt
Om 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å.
Nu är vi redo att köra testsviten:
$ ./runtests.py
...\> runtests.py
Nu 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.
Nä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.
Nä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.
Observera 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.
Observera
För denna handledning och det ärende vi arbetar med är det tillräckligt att testa mot SQLite, men det är möjligt (och ibland nödvändigt) att :ref:``köra testerna med en annan databas <running-unit-tests-settings>`. När du gör ändringar i användargränssnittet måste du köra Selenium-testerna.
Arbetar med en godkänd ny funktion¶
För denna handledning kommer vi att arbeta med en ”falsk accepterad biljett” som en fallstudie. Här är de imaginära detaljerna:
Ticket #99999 – Tillåt att göra toast
Django bör tillhandahålla en funktion django.shortcuts.make_toast() som returnerar 'toast'.
Vi kommer nu att implementera denna funktion och tillhörande tester.
Skapa en filial¶
Innan du gör några ändringar ska du skapa en ny gren för ärendet:
$ git checkout -b ticket_99999
...\> git checkout -b ticket_99999
Du 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.
Skriva några tester för din biljett¶
Fö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.
Ett 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.
Nu till vårt praktiska exempel.
Skriva ett test för ärende #99999¶
Fö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
from django.test import SimpleTestCase
class MakeToastTests(SimpleTestCase):
def test_make_toast(self):
self.assertEqual(make_toast(), "toast")
Detta test kontrollerar att make_toast() returnerar 'toast'.
Men den här testgrejen verkar ganska svår…
Om du aldrig har haft att göra med tester tidigare kan de se lite svåra ut att skriva vid första anblicken. Lyckligtvis är testning ett mycket stort ämne inom datorprogrammering, så det finns massor av information där ute:
En bra första titt på hur man skriver tester för Django finns i dokumentationen på Skriva och köra tester.
Dive Into Python (en gratis onlinebok för nybörjare i Python) innehåller en bra ”introduktion till enhetstestning”.
Efter att ha läst dem, om du vill ha något lite tjockare att sätta tänderna i, finns det alltid Python
unittest-dokumentationen.
Kör ditt nya test¶
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:
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
Om testerna kördes korrekt bör du se ett fel som motsvarar den testmetod vi lade till, med detta fel:
ImportError: cannot import name 'make_toast' from 'django.shortcuts'
Om 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.
Skriva koden för din biljett¶
Nu 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():
return "toast"
Nu 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:
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
Allt ska godkännas. Om det inte gör det, kontrollera att du har lagt till funktionen i rätt fil.
Kör Djangos testsvit för andra gången¶
Nä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.
För att köra hela Djangos testsvit, cd till Djangos tests/ katalog och kör:
$ ./runtests.py
...\> runtests.py
Skriva dokumentation¶
Det 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()``
================
.. function:: make_toast()
.. versionadded:: 2.2
Returns ``'toast'``.
Eftersom den här nya funktionen kommer att finnas med i en kommande version läggs den också till i release notes för nästa version av Django. Öppna release notes 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`
~~~~~~~~~~~~~~~~~~~~~~~
* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
Fö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.
Förhandsgranska dina ändringar¶
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:
$ git add --all
...\> git add --all
Visa sedan skillnaderna mellan din nuvarande kopia av Django (med dina ändringar) och den revision som du ursprungligen checkade ut tidigare i handledningen med:
$ git diff --cached
...\> git diff --cached
Använd piltangenterna för att flytta uppåt och nedåt.
diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
# Finally, fall back and assume it's a URL
return to
+
+
+def make_toast():
+ return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
Minor features
--------------
+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
my_objects = list(MyModel.objects.filter(published=True))
if not my_objects:
raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+ def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast')
Nä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.
Överföra ändringarna¶
För att bekräfta ändringarna:
$ git commit
...\> git commit
Detta öppnar en textredigerare för att skriva commit-meddelandet. Följ riktlinjerna för commit-meddelanden och skriv ett meddelande som:
Fixed #99999 -- Added a shortcut function to make toast.
Tryck på commit och gör en pull request¶
Nä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):
$ git push origin ticket_99999
...\> git push origin ticket_99999
Du 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.
Gö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”.
Nästa steg¶
Grattis, 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.
Nu kan du använda dessa kunskaper på ett bra sätt genom att hjälpa till att förbättra Djangos kodbas.
Mer information för nya bidragsgivare¶
Innan 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å:
Du 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å biljetter 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.
Hitta din första riktiga biljett¶
När du har gått igenom en del av den informationen är du redo att gå ut och hitta en egen biljett 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.
Om 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å biljetter som nämndes i länken till Djangos dokumentation på claiming tickets and submitting branches.
Vad händer härnäst efter att du har skapat en pull request?¶
Nä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 Triagering av biljetter för detaljer.
