Snabbstartsguide för sprint

Det här dokumentet förklarar hur du förbereder dig för att bidra till Django. Det är avsett att användas under sprintar eller av personer som redan är vana vid att bidra till Python-projekt med öppen källkod.

Den här guiden förutsätter att du känner till:

• Git (se Arbeta med Git och GitHub)

• Hantering av flera Python-versioner

• Hantering av Python-beroenden, inklusive virtuella miljöer

• Vad det innebär att köra tester och bygga dokumentation

Om något av detta är obekant, se Skriva ditt första bidrag till Django för en längre steg-för-steg-handledning.

Konfigurera

1. Forka kodförrådet på GitHub, klona din fork till din dator och konfigurera en fjärrreferens till Djangos uppströmskodförråd:

   Linux/macOS

   $ git clone https://github.com/YourGitHubName/django.git
   $ cd django
   $ git remote add upstream https://github.com/django/django.git
   

   Windows

   ...\> git clone https://github.com/YourGitHubName/django.git
   ...\> cd django
   ...\> git remote add upstream https://github.com/django/django.git
   

2. Bekräfta att du använder en kompatibel Python-version, och konfigurera sedan en virtuell miljö:

   $ # This needs to be >= 3.12
   $ python -V
   $ python -m venv ~/.virtualenvs/djangodev
   $ source ~/.virtualenvs/djangodev/bin/activate
   

   Om du inte använder ett Unix-liknande system, se de plattformspecifika instruktionerna.

3. Installera beroendena för att köra testerna och bygga dokumentationen:

   Linux/macOS

   $ python -m pip install -U pip
   $ python -m pip install -e . -r tests/requirements/py3.txt -r docs/requirements.txt
   

   Windows

   ...\> py -m pip install -U pip
   ...\> py -m pip install -e . -r tests\requirements\py3.txt -r docs\requirements.txt
   

4. Installera pre-commit-hookar så att formatering och lintning körs automatiskt före varje commit:

   Linux/macOS

   $ python -m pip install pre-commit
   $ pre-commit install
   

   Windows

   ...\> py -m pip install pre-commit
   ...\> pre-commit install
   

   Se Kontroller före åtagandet för ytterligare information.

5. Kör testerna:

   Linux/macOS

   $ ./tests/runtests.py
   

   Windows

   ...\> tests\runtests.py
   

   Se Kör enhetstesterna för mer information. Även om samtliga tester passerar i CI, kanske de inte gör det i varje persons lokala miljö. Exempelvis garanteras testsviten bara att passera med den senaste underutgåvan av varje Python-version som stöds. Det är möjligt att du stöter på fel vid användning av en tidigare underutgåva.

   Om du har ett fåtal fel kan det vara värt att undersöka om de är kända problem eller använda projektet django-docker-box för att köra testerna. Eftersom detta är en sprint kan det vara mer värdefullt att arbeta med det aktuella ärendet än att utreda ett märkligt problem med maskinens konfiguration. Anteckna de tester som misslyckas innan du börjar, så att du kan avgöra om ett senare fel orsakades av dina ändringar.

6. Bygg dokumentationen:

   Linux/macOS

   $ cd docs && make html && cd ..
   

   Windows

   ...\> cd docs && make.bat html && cd ..
   

Hitta ett ärende att arbeta med

Att hitta ett lämpligt ärende att arbeta med är utmanande. Det är viktigt att läsa det här avsnittet innan du försöker göra det.

Bedöma ärenden

När du går igenom ärenden är det en god idé att begränsa sökningen till accepterade ärenden som skapats de senaste fem åren. Äldre ärenden är gamla av en anledning: de är oftast fortfarande öppna eftersom de är svåra, omstridda eller både och. Du får gärna försöka med ett, men räkna med att det kräver stor uthållighet.

Överväg att använda komponentfilteralternativet i Trac för att begränsa sökningen till områden som du använt tidigare. Om du har använt formulär i några Django-appar kan du överväga att filtrera till formulärkomponenten. Om du däremot aldrig arbetat med geospatiala projekt är det troligen klokt att undvika django.contrib.gis. Här är till exempel ärendena för dokumentationskomponenten.

Sätt att hitta ärenden

Det finns två rekommenderade sätt att hitta ett ärende:

• Titta på lättplockade ärenden.

• Använd vulture-metoden.

Vulture-metoden innebär att leta efter accepterade ärenden som inte har berörts på minst sex månader. Det ideala ärendet har en PR kopplad till sig där en kodgranskning innehåller uttryckliga önskemål om ändringar, och författaren har inte svarat på minst sex månader, vare sig i PR:en eller i ärendet. Innan du tar över ett sådant, lämna en kommentar både i ärendet och i PR:en och meddela författaren att du fortsätter arbetet.

Du kan se listan med ärenden som möjligen kan tas över här. Följande filter används:

• Triage-steg = Accepterad

• Patch behöver förbättras = Ja

• Skapad = mellan för 5 år sedan och i dag

• Ändrad = mellan för 5 år sedan och för 6 månader sedan

Ta ansvar för ett ärende

När du hittar ett ärende gör du dig själv till ägare genom att klicka på knappen ”Modify Ticket” nära sidans nederkant, välja alternativknappen ”assign to” i avsnittet ”Action” och klicka på ”Submit changes”. Ditt användarnamn fylls i som standard i textrutan. Se ”Att göra anspråk på” ärenden för den fullständiga dokumentationen.

Skapa en gren för ärendet

Hur du skapar din gren beror på om ärendet redan har arbete kopplat till sig.

Börja från början

När du tagit ansvar för ärendet skapar du en gren för ditt arbete och ersätter TicketNumber med det faktiska Trac-ärendenumret:

Linux/macOS

$ git fetch upstream
$ git checkout -b ticket_TicketNumber upstream/main

Windows

...\> git fetch upstream
...\> git checkout -b ticket_TicketNumber upstream/main

När arbetet är klart pushar du grenen till din fork och öppnar en pull request. Se Inlämning av bidrag för hela processen.

Fortsätta någon annans arbete

Om du fortsätter arbetet från någon annans pull request på GitHub kan det vara knepigt. Du behöver hämta deras gren, men sedan pusha den till din fork av GitHub-kodförrådet.

Kör följande och ersätt PRNumber och TicketNumber med de faktiska numren för pull requesten respektive Trac-ärendet:

Linux/macOS

$ git fetch upstream pull/PRNumber/head:ticket_TicketNumber
$ git checkout ticket_TicketNumber
$ git push origin ticket_TicketNumber

Windows

...\> git fetch upstream pull/PRNumber/head:ticket_TicketNumber
...\> git checkout ticket_TicketNumber
...\> git push origin ticket_TicketNumber

För att till exempel fortsätta PR 8000 för ärende 123 kör du:

Linux/macOS

$ git fetch upstream pull/8000/head:ticket_123
$ git checkout ticket_123
$ git push origin ticket_123

Windows

...\> git fetch upstream pull/8000/head:ticket_123
...\> git checkout ticket_123
...\> git push origin ticket_123

När du förbereder din commit, läs våra commit-riktlinjer, särskilt hur medförfattare ska anges.