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 en Trac-biljett.

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

”Att göra anspråk på” biljetter

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 biljettsystem. Om du har ett konto men har glömt ditt lösenord kan du återställa det med hjälp av sidan återställning av lösenord.

• 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, kontrollera att ingen annan har gjort anspråk på det. Detta gör du genom att titta på avsnittet ”Ägs av” i ärendet. Om det är tilldelat ”ingen” är det tillgängligt för att göras anspråk på. Annars kan någon annan arbeta på den här ärendet. Hitta antingen en annan bugg/funktion att arbeta med eller kontakta utvecklaren som arbetar med ärendet för att erbjuda din hjälp. Om ett ärende har varit tilldelat i veckor eller månader utan någon aktivitet är det förmodligen säkert att tilldela det till dig själv igen.

• 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å biljettsidan. När du är inloggad kan du klicka på knappen ”Modify Ticket” längst ner på sidan.

• Gör anspråk på biljetten 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 ”Skicka ändringar” längst ned för att spara.

Observera

Django Software Foundation begär att alla som bidrar med mer än en trivial förändring, till Django signerar och skickar in ett Contributor License Agreement, detta säkerställer att Django Software Foundation har en tydlig licens till alla bidrag vilket möjliggör en tydlig licens för alla användare.

Biljettåterförsäljarnas ansvar

När du har gjort anspråk på en biljett har du ett ansvar att arbeta med den biljetten 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å biljetten återkallas.

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

Vilka biljetter ska tas i anspråk?

Att gå igenom stegen för att göra anspråk på biljetter ä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 biljettkrav. Skicka in dina ändringar direkt och du är klar!

Det är alltid acceptabelt, oavsett om någon har gjort anspråk på 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:

• Den kod som krävs för att åtgärda ett problem eller lägga till en funktion är en viktig del av en lösning, men det är inte den enda delen. En bra lösning bör också innehålla ett regressionstest för att validera det beteende som har åtgärdats och för att förhindra att problemet uppstår igen. Om det finns ärenden som är relevanta för den kod du har skrivit kan du också nämna ärendenumren i några kommentarer i testet, så att man enkelt kan spåra de relevanta diskussionerna efter att din patch har publicerats och ärendena har stängts.

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

När du tror att ditt arbete är redo att granskas skickar du en GitHub pull request. Om du av någon anledning inte kan skicka en pull request kan du också använda patchar i Trac. Följ dessa riktlinjer när du använder den här stilen.

• 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 biljettspåraren 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.

Bidrag som kräver återkoppling från samhället

En bredare samhällsdiskussion 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 samhället.

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 :ref:``process för att föreslå nya funktioner <requesting-features>`. 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 :ref:deprecation policy <internal-release-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 samhällsinformation om större nya funktioner.

Innan du överväger att skriva en DEP rekommenderas det att du först öppnar en diskussion enligt processen för att föreslå nya funktioner. På så sätt kan deltagarna ge feedback och hjälpa till att förfina förslaget. När DEP är klart röstar Steering Council om huruvida det 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 :ref:deprecation policy<internal-release-deprecation-policy> beskriver, bör den första utgåvan av Django som deprecierar en funktion (A.B) ge upphov till en RemovedInDjangoXXWarning (där XX är den Django-version där funktionen kommer att tas bort) när den deprecierade funktionen anropas. Förutsatt att vi har bra testtäckning omvandlas dessa varningar till fel när :ref:kör testsviten <running-unit-tests> med varningar aktiverade: python -Wa runtests.py. När du lägger till en RemovedInDjangoXXWarning måste du därför eliminera eller tysta alla varningar som genereras när du kör testerna.

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 RemovedInDjangoXXWarning
   
   
   @ignore_warnings(category=RemovedInDjangoXXWarning)
   def test_foo(self): ...
   

2. För ett helt testfall:

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

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

from django.utils.deprecation import RemovedInDjangoXXWarning


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

Det är viktigt att inkludera en RemovedInDjangoXXWarning-kommentar ovanför kod som inte har någon varningsreferens, men som måste ändras eller tas bort när deprecationen upphör. Detta kan inkludera krokar som har lagts till för att behålla det tidigare beteendet, eller fristående objekt som är onödiga eller oanvända när avskrivningen upphör. Till exempel:

import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning


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


def foo():
    warnings.warn(
        "foo() is deprecated.",
        category=RemovedInDjangoXXWarning,
        stacklevel=2,
    )
    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 versionsnoterna (docs/releases/A.B.txt) under rubriken ”Features deprecated in 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 du klar med avskrivningen. I varje :term:feature release <Feature release>, tas alla RemovedInDjangoXXWarning bort som matchar den nya versionen.

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 en accepterad biljett innan du fortsätter med granskningen.

Om pull request uppfyller alla kriterier nedan och inte är din egen, ställ in ”Triage Stage” på motsvarande Trac-biljett till ”Ready for checkin”. Om du har lämnat kommentarer för förbättring av pull request, kryssa i lämpliga flaggor på Trac-ärendet baserat på resultaten av din granskning: ”Patch behöver förbättras”, ”Behöver dokumentation” och/eller ”Behöver testas”. I mån av tid och intresse gör sammanslagarna en slutlig granskning av ”Klar för incheckning”-biljetterna och antingen bekräftar de ändringarna eller flyttar tillbaka dem till ”Accepterad” om ytterligare arbete behöver göras.

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.

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 en release note 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.

Alla kodändringar

• Överensstämmer kodningsstil med våra riktlinjer? Finns det några black, blacken-docs, flake8 eller isort fel? Du kan installera pre-commit krokarna för att automatiskt fånga upp 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 ändringen påverkar Django-admin eller HTML-utdata, har :ref:accessibility testing <accessibility-testing-baseline> gjorts?

Alla biljetter

• Ä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 till dig själv i filen AUTHORS och skicka in ett Contributor License Agreement.

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