# Django 5.2.8 documentation

# 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.

See the Arbeta med Git och GitHub for more details on how to use 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 ditt lösenord kan du återställa det med hjälp av sidan password reset page.

- 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å ä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 ”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.

### 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 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:

- The code required to fix a problem or add a feature is an essential part of a solution, but it is not the only part. A good fix should also include a regression test to validate the behavior that has been fixed and to prevent the problem from arising again. Also, if some tickets are relevant to the code that you’ve written, mention the ticket numbers in some comments in the test so that one can easily trace back the relevant discussions after your patch gets committed, and the tickets get closed.

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

When you think your work is ready to be reviewed, send a GitHub pull request. If you can’t send a pull request for some reason, you can also use patches in Trac. When using this style, follow these guidelines.

- 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.

## 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 du först öppnar en diskussion enligt processen för att föreslå nya funktioner. På så sätt kan gemenskapen ge återkoppling 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 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 kör testsviten 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 hooks 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, django_file_prefixes

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

    def foo():
        warnings.warn(
            "foo() is deprecated.",
            category=RemovedInDjangoXXWarning,
            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 du klar med avskrivningen. I varje feature release, tas alla `RemovedInDjangoXXWarning` bort som matchar den nya versionen.

The `django.utils.deprecation` module provides some helpful deprecation utilities, such as a `@deprecate_posargs` decorator to assist with converting positional-or-keyword arguments to keyword-only. See the inline documentation in the module source.

## 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 request uppfyller alla kriterier nedan och inte är din egen, ställ in ”Triage Stage” på motsvarande Trac-ärende 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”-ärenden 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 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.

### Alla kodändringar

- Does the coding style conform to our guidelines? Are there any `black`, `blacken-docs`, `flake8`, `isort`, or `zizmor` errors? You can install the pre-commit hooks to automatically catch these errors.

- 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 accessibility testing gjorts?

### 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 till dig själv i filen AUTHORS och 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.