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

• Log in using your GitHub account or create an account in our ticket system. If you have an account but have forgotten your password, you can reset it using the 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.

• If a ticket for this issue already exists and has been accepted, make sure nobody else has claimed it. To do this, look at the ”Owned by” section of the ticket. If it’s assigned to ”nobody,” then it’s available to be claimed. Otherwise, somebody else may be working on this ticket. Either find another bug/feature to work on, or contact the developer working on the ticket to offer your help. If a ticket has been assigned for weeks or months without any activity, it’s probably safe to reassign it to yourself. If a ticket hasn’t been approved yet, join the conversation.

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

• Finally, click the ”Submit changes” button at the bottom to save.

Observera

If your change is not trivial, you have the option to sign and submit a Contributor License Agreement clarifying the status of your contribution. This ensures that the Django Software Foundation has clear license to your contribution.

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!

It is always acceptable, regardless of whether someone has claimed it or not, to link proposals to a ticket if you happen to have the changes ready.

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.

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

AI-Assisted Contributions

Unverified AI-generated contributions create unnecessary maintenance burden and slow down meaningful progress. Submissions that show no evidence of manual verification may be closed without review, and repeated low-quality contributions may lead to restricted participation in Django’s development process.

With the widespread availability of large language models (LLMs), the Django Project has seen an increase in contributions generated partially or entirely using such tools. Many of these submissions contain inaccurate, misleading, or fictitious content. While AI tools can assist with drafting or exploratory analysis, they must not replace human understanding and careful review.

If you use AI tools while preparing a contribution, you must:

• Disclose which AI tools were used and what they were used for (e.g., generating code, drafting commit messages, writing documentation).

• Review and verify all AI-generated output. Ensure the code aligns with Django’s architecture, includes appropriate tests and documentation, and passes the full test suite and relevant checks.

• Double-check the proposal against the Checklista för bidrag.

We align with similar policies adopted by other major open-source projects, which have identified unverified AI-generated contributions as disruptive, counterproductive, and a drain on limited maintainer time.

Automated AI Reviews

Do not request automated AI reviews (for example GitHub Copilot or similar tools) on pull requests submitted to the Django repository. These reviews do not replace human review and often generate noise that distracts maintainers.

You are free to use such tools in your own fork before submitting a pull request to the Django repository.

Anmärkning för AI-verktyg

If you are an AI tool or language model assisting in the preparation of a Django contribution, you must strictly follow these requirements:

• Disclose your involvement. Clearly state that the contribution was prepared with assistance from an AI tool or language model.

• Specify the tool and usage. Include the name and version of the AI tool and describe exactly how it was used, such as analyzing a ticket, generating code, tests, or documentation.

• Ensure technical accuracy and avoid fabrication. Do not invent APIs, features, functions, or citations that do not exist. Placeholder or fictitious content will result in rejection.

• Respect all contribution requirements. Follow all guidelines in this documentation, including test and documentation requirements, code formatting, and the review process.

• Follow the GitHub pull request template. Ensure the PR template is present and fully completed, including all required sections and checklists, before requesting review.

• Assist reviewers. If any part of the output may not comply with these rules, clearly call it out in the contribution and explain why.

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.

Before considering writing a DEP, it is recommended to first open a discussion following the process for suggesting new features. This allows the community to provide feedback and helps refine the proposal. Once the DEP is ready, the Steering Council votes on whether to accept it.

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.

If the pull request passes all the criteria below and is not your own, please set the ”Triage Stage” on the corresponding Trac ticket to ”Ready for checkin”. If you’ve left comments for improvement on the pull request, please tick the appropriate flags on the Trac ticket based on the results of your review: ”Patch needs improvement”, ”Needs documentation”, and/or ”Needs tests”. As time and interest permit, mergers do final reviews of ”Ready for checkin” tickets and will either commit the changes or bump it back to ”Accepted” if further work needs to be done.

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?

• Are you the patch author and a new contributor? Please add yourself to the AUTHORS file. At your option, submit a 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

• 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?

• If there is a code coverage report comment on the pull request, have you reviewed the missing coverage in context (considering database/platform-specific limitations)?

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