Inlämning av bidrag

Vi är alltid tacksamma för bidrag till Djangos kod. Faktum är att felrapporter med tillhörande bidrag kommer att åtgärdas * långt* snabbare än de utan en lösning.

Rättelser av stavfel och triviala dokumentationsändringar

Om du åtgärdar ett riktigt trivialt problem, till exempel ändrar ett ord i dokumentationen, är det bästa sättet att tillhandahålla korrigeringen att använda GitHub pull requests utan ett Trac-ärende.

Se Arbeta med Git och GitHub för mer information om hur du använder pull requests.

”Att göra anspråk på” ärenden

I ett open source-projekt med hundratals medarbetare runt om i världen är det viktigt att hantera kommunikationen på ett effektivt sätt så att arbetet inte dubbleras och medarbetarna kan vara så effektiva som möjligt.

Därför är vår policy att bidragsgivare ska ”göra anspråk” på ärenden för att låta andra utvecklare veta att en viss bugg eller funktion bearbetas.

Om du har identifierat ett bidrag som du vill göra och du är kapabel att fixa det (mätt med din kodningsförmåga, kunskap om Django internals och tidstillgång), gör du anspråk på det genom att följa dessa steg:

• Logga in med ditt GitHub-konto eller skapa ett konto i vårt ärendesystem. Om du har ett konto men har glömt lösenordet kan du återställa det på sidan för lösenordsåterställning.

• Om det inte finns något ärende för denna fråga ännu, skapa ett i vår ticket tracker. Kom ihåg att förslag på nya funktioner bör följa processen för att föreslå nya funktioner.

• Om det redan finns ett ärende för detta problem och det har accepterats, kontrollera att ingen annan har tagit ansvar för det. Titta då i avsnittet ”Owned by” i ärendet. Om det är tilldelat ”nobody” går det att ta över. Annars kan någon annan arbeta med ärendet. Hitta antingen ett annat fel eller en annan funktion att arbeta med, eller kontakta utvecklaren som arbetar med ärendet och erbjud din hjälp. Om ett ärende har varit tilldelat i veckor eller månader utan aktivitet är det troligen säkert att tilldela det till dig själv igen. Om ett ärende ännu inte har godkänts, delta i diskussionen.

• Logga in på ditt konto, om du inte redan har gjort det, genom att klicka på ”GitHub Login” eller ”DjangoProject Login” längst upp till vänster på ärendesidan. När du är inloggad kan du klicka på knappen ”Modify Ticket” längst ner på sidan.

• Gör anspråk på ärendet genom att klicka på alternativknappen ”tilldela till” i avsnittet ”Åtgärd”. Ditt användarnamn kommer som standard att fyllas i i textrutan.

• Klicka slutligen på knappen ”Submit changes” längst ned för att spara.

Observera

Om din ändring inte är trivial kan du välja att underteckna och skicka in ett Contributor License Agreement som klargör bidragets status. Det säkerställer att Django Software Foundation har en tydlig licens för ditt bidrag.

Ansvaret för ärendebedömmare

När du har gjort anspråk på ett ärende har du ett ansvar att arbeta med det ärendet inom rimlig tid. Om du inte har tid att arbeta med ärendet får du antingen ta tillbaka det eller inte göra anspråk på det över huvud taget!

Om det inte sker några framsteg med ett visst ärende under en vecka eller två kan en annan utvecklare be dig att avstå från ärendet så att det inte längre är monopoliserat och någon annan kan göra anspråk på det.

Om du har gjort anspråk på ett ärende och det tar lång tid (dagar eller veckor) att koda det ska du hålla alla uppdaterade genom att skriva kommentarer till ärendet. Om du inte tillhandahåller regelbundna uppdateringar och inte svarar på en begäran om en lägesrapport kan ditt anspråk på ärendet återkallas.

Som alltid är mer kommunikation bättre än mindre kommunikation!

Vilka ärenden ska bedömmas?

Att gå igenom stegen för att göra anspråk på ärenden är överflödigt i vissa fall.

När det gäller små ändringar, t.ex. stavfel i dokumentationen eller små buggar som bara tar några minuter att åtgärda, behöver du inte göra några ärendekrav. Skicka in dina ändringar direkt och du är klar!

Det är alltid tillåtet, oavsett om någon har tagit ansvar för det eller inte, att länka förslag till ett ärende om du råkar ha ändringarna klara.

Bidragsstil

Se till att alla bidrag du ger uppfyller åtminstone följande krav:

• Koden som krävs för att rätta ett problem eller lägga till en funktion är en väsentlig del av en lösning, men den är inte den enda delen. En bra rättning bör även innehålla ett regressionstest som validerar det rättade beteendet och hindrar problemet från att uppstå igen.

• Om koden lägger till en ny funktion eller ändrar beteendet hos en befintlig funktion ska ändringen också innehålla dokumentation.

När du anser att ditt arbete är redo att granskas, skicka en GitHub-pull request. Om du av någon anledning inte kan skicka en pull request kan du också använda patchar i Trac. När du använder den stilen ska du följa dessa riktlinjer.

• Skicka in korrigeringar i det format som returneras av kommandot git diff.

• Bifoga patchar till ett ärende i ticket tracker, med hjälp av knappen ”attach file”. Lägg inte till patchen i beskrivningen eller kommentaren till ärendet om det inte är en patch på en rad.

• Namnge patchfilen med tillägget .diff; detta gör att ärendehanteraren kan tillämpa korrekt syntaxmarkering, vilket är till stor hjälp.

Oavsett hur du skickar in ditt arbete ska du följa dessa steg.

• Se till att din kod uppfyller kraven i vår checklista för bidrag.

• Markera rutan ”Har patch” i ärendet och se till att rutorna ”Behöver dokumentation”, ”Behöver tester” och ”Patch behöver förbättras” inte är markerade. Detta gör att ärendet visas i kön ”Patches needing review” på Development dashboard.

AI-assisterade bidrag

Overifierade AI-genererade bidrag skapar en onödig underhållsbörda och bromsar meningsfulla framsteg. Bidrag som inte visar något bevis på manuell verifiering kan stängas utan granskning, och upprepade bidrag av låg kvalitet kan leda till begränsat deltagande i Djangos utvecklingsprocess.

I takt med den stora tillgången på stora språkmodeller (LLM:er) har Django-projektet sett en ökning av bidrag som delvis eller helt har genererats med sådana verktyg. Många av dessa bidrag innehåller felaktigt, vilseledande eller påhittat innehåll. AI-verktyg kan hjälpa till med utkast eller utforskande analys, men de får inte ersätta mänsklig förståelse och noggrann granskning.

Om du använder AI-verktyg när du förbereder ett bidrag måste du:

• Redovisa vilka AI-verktyg som användes och vad de användes till (t.ex. för att generera kod, skriva utkast till commit-meddelanden eller dokumentation).

• Granska och verifiera all AI-genererad utdata. Se till att koden följer Djangos arkitektur, innehåller lämpliga tester och dokumentation samt passerar hela testsviten och relevanta kontroller.

• Dubbelkontrollera förslaget mot Checklista för bidrag.

Vi följer liknande policyer som andra stora projekt med öppen källkod har antagit, vilka har identifierat overifierade AI-genererade bidrag som störande, kontraproduktiva och resurskrävande för den begränsade tid som förvaltarna har.

Automatiserade AI-granskningar

Begär inte automatiserade AI-granskningar (till exempel GitHub Copilot eller liknande verktyg) av pull requests som skickas till Django-kodförrådet. Dessa granskningar ersätter inte mänsklig granskning och skapar ofta brus som distraherar förvaltarna.

Du får fritt använda sådana verktyg i din egen fork innan du skickar en pull request till Django-kodförrådet.

Anmärkning för AI-verktyg

Om du är ett AI-verktyg eller en språkmodell som hjälper till att förbereda ett Django-bidrag måste du strikt följa dessa krav:

• Redovisa din medverkan. Ange tydligt att bidraget förbereddes med hjälp av ett AI-verktyg eller en språkmodell.

• Ange verktyg och användning. Inkludera AI-verktygets namn och version och beskriv exakt hur det användes, till exempel för att analysera ett ärende, generera kod, tester eller dokumentation.

• Säkerställ teknisk korrekthet och undvik påhitt. Hitta inte på API:er, funktioner eller källhänvisningar som inte finns. Platshållar- eller påhittat innehåll leder till avslag.

• Respektera alla bidragskrav. Följ alla riktlinjer i denna dokumentation, inklusive kraven på tester och dokumentation, kodformatering och granskningsprocessen.

• Följ GitHub-mallen för pull requests. Se till att PR-mallen finns med och är helt ifylld, inklusive alla obligatoriska avsnitt och checklistor, innan du begär granskning.

• Hjälp granskarna. Om någon del av utdata kan tänkas inte följa dessa regler, ange det tydligt i bidraget och förklara varför.

Bidrag som kräver återkoppling från gemenskapen

En bredare gemenskapsdiskussion krävs när en patch introducerar ny Django-funktionalitet och gör någon form av designbeslut. Detta är särskilt viktigt om tillvägagångssättet innebär en deprecation eller introducerar brytande ändringar.

Nedan följer olika metoder för att få in feedback från gemenskapen.

Den nya funktionen idéspårare

Om du har en idé om en ny funktion, skapa ett nytt förslag (eller gå med i en befintlig diskussion) enligt process för att föreslå nya funktioner. Du bör förklara behovet av ändringen, gå in i detalj på tillvägagångssättet och diskutera alternativ.

Django-forumet

Du kan föreslå en förändring (som inte är en idé om en ny funktion) på Django Forum. Du bör förklara behovet av förändringen, gå in i detalj på tillvägagångssättet och diskutera alternativ.

Bifoga gärna en länk till sådana diskussioner i dina bidrag.

Paket från tredje part

Django accepterar inte experimentella funktioner. Alla funktioner måste följa vår deprecation policy. Därför kan det ta månader eller år för Django att iterera på en API-design.

Om du behöver feedback från användare på ett publikt gränssnitt är det bättre att skapa ett tredjepartspaket först. Du kan iterera på det publika API:et mycket snabbare, samtidigt som du validerar behovet av funktionen.

När det här paketet blir stabilt och det finns tydliga fördelar med att införliva aspekter i Django-kärnan, är nästa steg att föreslå att det ska inkluderas genom att följa processen för att föreslå nya funktioner.

Förslag till förbättring av Django (DEP)

I likhet med Pythons PEPs har Django Django Enhancement Proposals eller DEPs. Ett DEP är ett designdokument som ger information till Django-gemenskapen eller beskriver en ny funktion eller process för Django. De ger kortfattade tekniska specifikationer för funktioner, tillsammans med motiveringar. DEP är också den primära mekanismen för att föreslå och samla in gemenskapsinformation om större nya funktioner.

Innan du överväger att skriva en DEP rekommenderas det att först öppna en diskussion enligt processen för att föreslå nya funktioner. Det gör att communityn kan ge återkoppling och bidrar till att förfina förslaget. När DEP:n är klar röstar Steering Council om den ska accepteras.

Några exempel på DEP:er som har godkänts och implementerats fullt ut:

• DEP 181: ORM-uttryck

• DEP 182: Flera mallmotorer

• DEP 201: Förenklad syntax för routning

Avveckling av en funktion

Det finns ett par anledningar till att kod i Django kan vara föråldrad:

• Om en funktion har förbättrats eller modifierats på ett bakåtkompatibelt sätt kommer den gamla funktionen eller det gamla beteendet att avskrivas.

• Ibland kommer Django att inkludera en backport av ett Python-bibliotek som inte ingår i en version av Python som Django för närvarande stöder. När Django inte längre behöver stödja den äldre versionen av Python som inte innehåller biblioteket, kommer biblioteket att avskrivas i Django.

Som utfasningspolicyn beskriver ska den första Django-utgåva som fasar ut en funktion (A.B) utlösa RemovedInDjangoXXXXWarning (där XXXX är Django-versionen då funktionen tas bort) när den utfasade funktionen anropas. Förutsatt god testtäckning omvandlas varningarna till fel när testsviten körs med varningar aktiverade: python -Wa runtests.py. När du lägger till en RemovedInDjangoXXXXWarning behöver du därför eliminera eller tysta alla varningar som skapas när testerna körs.

Det första steget är att ta bort all användning av det föråldrade beteendet av Django själv. Därefter kan du tysta varningar i tester som faktiskt testar det föråldrade beteendet genom att använda dekoratorn ignore_warnings, antingen på test- eller klassnivå:

1. I ett visst test:

   from django.test import ignore_warnings
   from django.utils.deprecation import RemovedInDjangoXXXXWarning
   
   
   @ignore_warnings(category=RemovedInDjangoXXXXWarning)
   def test_foo(self): ...
   

2. För ett helt testfall:

   from django.test import ignore_warnings
   from django.utils.deprecation import RemovedInDjangoXXXXWarning
   
   
   @ignore_warnings(category=RemovedInDjangoXXXXWarning)
   class MyDeprecatedTests(unittest.TestCase): ...
   

Du bör också lägga till ett test för deprecation warning:

from django.utils.deprecation import RemovedInDjangoXXXXWarning


def test_foo_deprecation_warning(self):
    msg = "Expected deprecation message"
    with self.assertWarnsMessage(RemovedInDjangoXXXXWarning, msg) as ctx:
        # invoke deprecated behavior
        ...
    self.assertEqual(ctx.filename, __file__)

Det är viktigt att lägga till en RemovedInDjangoXXXXWarning-kommentar ovanför kod som saknar varningsreferens, men som behöver ändras eller tas bort när utfasningen upphör. Det kan gälla hookar som har lagts till för att bevara tidigare beteende, eller fristående delar som är onödiga eller oanvända när utfasningen upphör. Till exempel:

import warnings
from django.utils.deprecation import RemovedInDjangoXXXXWarning, django_file_prefixes


# RemovedInDjangoXXXXWarning.
def old_private_helper():
    # Helper function that is only used in foo().
    pass


def foo():
    warnings.warn(
        "foo() is deprecated.",
        category=RemovedInDjangoXXXXWarning,
        skip_file_prefixes=django_file_prefixes(),
    )
    old_private_helper()
    ...

Slutligen finns det ett par uppdateringar av Djangos dokumentation att göra:

1. Om den befintliga funktionen är dokumenterad, markera den som föråldrad i dokumentationen med hjälp av ...deprecated:: A.B annotation. Inkludera en kort beskrivning och en anmärkning om uppgraderingsvägen om det är tillämpligt.

2. Lägg till en beskrivning av det borttagna beteendet, och uppgraderingsvägen om tillämpligt, i de aktuella versionsinformation (docs/releases/A.B.txt) under rubriken ”Funktioner utfasade i A.B”.

3. Lägg till en post i deprecation-tidslinjen (docs/internals/deprecation.txt) under rätt version som beskriver vilken kod som kommer att tas bort.

När du har slutfört dessa steg är utfasningen klar. I varje funktionsutgåva tas alla RemovedInDjangoXXXXWarnings som motsvarar den nya versionen bort.

Modulen django.utils.deprecation tillhandahåller några användbara verktyg för utfasning, till exempel dekoratorn @deprecate_posargs som hjälper till att konvertera argument som är positionella eller nyckelordsargument till enbart nyckelordsargument. Se dokumentationen i modulens källkod.

Testning med ett Django-projekt

Det är viktigt att testa lokala ändringar med hjälp av ett Django-projekt. Detta gör det möjligt att säkerställa att ändringarna beter sig som förväntat i en verklig miljö, särskilt för användarvänliga funktioner som mallar, formulär eller administratören.

För att göra detta:

1. Skapa en virtuell miljö och installera den klonade kopian av Django i redigerbart läge.

2. Sätt upp ett Django-projekt utanför källträdet (du kan använda första delen av handledningen för vägledning).

Med den här inställningen kommer alla ändringar som görs i Django-utcheckningen att träda i kraft omedelbart i testprojektet, vilket möjliggör manuell testning av bidrag mot en ny eller befintlig app.

Bidrag från JavaScript

För information om JavaScript-bidrag, se JavaScript-uppdateringar-dokumentationen.

Optimeringsplåster

Uppdateringar som syftar till att förbättra prestandan bör innehålla riktmärken som visar effekten av uppdateringen före och efter och dela med sig av kommandona så att granskarna kan reproducera dem.

django-asv riktmärken

django-asv övervakar Django-kodens prestanda över tid. Dessa riktmärken kan köras på en dragbegäran genom att märka dragbegäran med benchmark. Att lägga till dessa riktmärken uppmuntras starkt.

Checklista för bidrag

Använd denna checklista för att granska en pull request. Om detta bidrag inte skulle vara betraktas som trivialt, se först till att det har ett accepterat ärende innan du fortsätter med granskningen.

Om pull requesten uppfyller alla kriterier nedan och inte är din egen, sätt ”Triage Stage” på motsvarande Trac-ärende till ”Ready for checkin”. Om du har lämnat kommentarer om förbättringar i pull requesten, markera lämpliga flaggor i Trac-ärendet utifrån resultatet av din granskning: ”Patch needs improvement”, ”Needs documentation” och/eller ”Needs tests”. I den mån tid och intresse tillåter gör merger-ansvariga slutliga granskningar av ”Ready for checkin”-ärenden och antingen committar ändringarna eller flyttar tillbaka ärendet till ”Accepted” om ytterligare arbete krävs.

Om du vill bli medlem i triage & review team är grundliga granskningar av bidrag ett bra sätt att förtjäna förtroende.

Letar du efter en patch att granska? Kolla in avsnittet ”Patchar som behöver granskas” i Django Development Dashboard.

Vill du få din pull request granskad? Se till att Trac-flaggorna på ärendet är inställda så att ärendet visas i den kön.

Alla ärenden

• Är pull request en enda squashed commit med ett meddelande som följer vårt commit message format?

• Är du patchens författare och en ny bidragsgivare? Lägg då till dig själv i filen AUTHORS. Du kan välja att skicka in ett Contributor License Agreement.

• Har detta ett accepterat ärende på Trac? Alla bidrag kräver ett ärende om inte ändringen anses vara trivial.

Alla kodändringar

• Överensstämmer kodningsstilen med våra riktlinjer? Finns det några black-, blacken-docs-, flake8-, isort- eller zizmor-fel? Du kan installera pre-commit-hooks för att automatiskt upptäcka dessa fel.

• Om ändringen är bakåtkompatibel på något sätt, finns det en anteckning i releaseanteckningarna (docs/releases/A.B.txt)?

• Är Djangos testsvit godkänd?

• Om det finns en kommentar med en kodtäckningsrapport i pull requesten, har du då granskat den saknade täckningen i sitt sammanhang (med hänsyn till databas- eller plattformsspecifika begränsningar)?

• Om ändringen påverkar Django-admin eller HTML-utdata, har accessibility testing gjorts?

Dokumentation

• Byggs dokumentationen utan några fel (make html, eller make.bat html på Windows, från katalogen docs)?

• Följer dokumentationen riktlinjerna för skrivstil i Skriva dokumentation?

• Finns det några stavfel?

Vi checkar av WordPress.org forumet under hela veckan, och tittar efter buggar. Om du rapporterar en legitim bugg som vi kan reproducera, kommer vi loggar det och patcha för en kommande uppdatering. Men vi kan tyvärr inte ge anpassningstips eller hjälpa till att integrera med 3: e parts plugins eller teman

• Finns det ett korrekt regressionstest (testet ska misslyckas innan korrigeringen tillämpas)?

• Om det är en bugg som kvalificerar för en bakåtport till den stabila versionen av Django, finns det en release note i docs/releases/A.B.C.txt? Buggfixar som endast kommer att tillämpas på huvudgrenen behöver inte en utgivningsanteckning.

Nya funktioner

• Finns det tester för att ”träna” all den nya koden?

• Finns det versionsinformation i docs/releases/A.B.txt?

• Finns det dokumentation för funktionen och är den annoterad på lämpligt sätt med .. versionadded:: A.B eller .. versionchanged:: A.B?

Avveckling av en funktion

Se guiden Avveckling av en funktion.