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.
\nOm 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.
\nSee Arbeta med Git och GitHub for more\ndetails on how to use pull requests.
\nI 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.
\nDä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.
\nOm 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:
\nLog in using your GitHub account or create an account in our ticket\nsystem. If you have an account but have forgotten your password, you can\nreset 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\nnobody else has claimed it. To do this, look at the ”Owned by” section of\nthe ticket. If it’s assigned to ”nobody,” then it’s available to be claimed.\nOtherwise, somebody else may be working on this ticket. Either find another\nbug/feature to work on, or contact the developer working on the ticket to\noffer your help. If a ticket has been assigned for weeks or months without\nany activity, it’s probably safe to reassign it to yourself. If a ticket\nhasn’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.
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!
\nOm 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.
\nOm 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.
\nSom alltid är mer kommunikation bättre än mindre kommunikation!
\nAtt gå igenom stegen för att göra anspråk på ärenden är överflödigt i vissa fall.
\nNä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!
\nIt is always acceptable, regardless of whether someone has claimed it or not,\nto link proposals to a ticket if you happen to have the changes ready.
\nSe till att alla bidrag du ger uppfyller åtminstone följande krav:
\nThe code required to fix a problem or add a feature is an essential part\nof a solution, but it is not the only part. A good fix should also include a\nregression test to\nvalidate the behavior that has been fixed and to prevent the problem from\narising again. Also, if some tickets are relevant to the code that you’ve\nwritten, mention the ticket numbers in some comments in the test so that one\ncan easily trace back the relevant discussions after your patch gets\ncommitted, 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\nrequest. If you can’t\nsend a pull request for some reason, you can also use patches in Trac. When\nusing this style, follow these guidelines.
\nSkicka 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.
\nSe 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.
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.
\nNedan följer olika metoder för att få in feedback från gemenskapen.
\nOm 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.
\nDu 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.
\nBifoga gärna en länk till sådana diskussioner i dina bidrag.
\nDjango 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.
\nOm 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.
\nNä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.
\nI 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.
\nBefore considering writing a DEP, it is recommended to first open a discussion\nfollowing the process for suggesting new features.\nThis allows the community to provide feedback and helps refine the proposal.\nOnce the DEP is ready, the Steering Council votes on\nwhether to accept it.
\nNågra exempel på DEP:er som har godkänts och implementerats fullt ut:
\n\nDet finns ett par anledningar till att kod i Django kan vara föråldrad:
\nOm 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å:
I ett visst test:
\nfrom django.test import ignore_warnings\nfrom django.utils.deprecation import RemovedInDjangoXXWarning\n\n\n@ignore_warnings(category=RemovedInDjangoXXWarning)\ndef test_foo(self): ...\nFör ett helt testfall:
\nfrom django.test import ignore_warnings\nfrom django.utils.deprecation import RemovedInDjangoXXWarning\n\n\n@ignore_warnings(category=RemovedInDjangoXXWarning)\nclass MyDeprecatedTests(unittest.TestCase): ...\nDu bör också lägga till ett test för deprecation warning:
\nfrom django.utils.deprecation import RemovedInDjangoXXWarning\n\n\ndef test_foo_deprecation_warning(self):\n msg = "Expected deprecation message"\n with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg) as ctx:\n # invoke deprecated behavior\n ...\n self.assertEqual(ctx.filename, __file__)\nDet ä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\nfrom django.utils.deprecation import RemovedInDjangoXXWarning, django_file_prefixes\n\n\n# RemovedInDjangoXXWarning.\ndef old_private_helper():\n # Helper function that is only used in foo().\n pass\n\n\ndef foo():\n warnings.warn(\n "foo() is deprecated.",\n category=RemovedInDjangoXXWarning,\n skip_file_prefixes=django_file_prefixes(),\n )\n old_private_helper()\n ...\nSlutligen finns det ett par uppdateringar av Djangos dokumentation att göra:
\nOm 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.
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”.
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\nutilities, such as a @deprecate_posargs decorator to assist with converting\npositional-or-keyword arguments to keyword-only. See the inline documentation\nin the module source.
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.
\nFör att göra detta:
\nSkapa en virtuell miljö och installera den klonade kopian av Django i redigerbart läge.
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.
\nFör information om JavaScript-bidrag, se JavaScript-uppdateringar-dokumentationen.
\nUppdateringar 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.
\ndjango-asv riktmärkenLink to this heading#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.
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.
\nIf the pull request passes all the criteria below and is not your own, please\nset the ”Triage Stage” on the corresponding Trac ticket to ”Ready for checkin”.\nIf you’ve left comments for improvement on the pull request, please tick the\nappropriate flags on the Trac ticket based on the results of your review:\n”Patch needs improvement”, ”Needs documentation”, and/or ”Needs tests”. As time\nand interest permit, mergers do final reviews of ”Ready for checkin” tickets\nand will either commit the changes or bump it back to ”Accepted” if further\nwork needs to be done.
\nOm du vill bli medlem i triage & review team är grundliga granskningar av bidrag ett bra sätt att förtjäna förtroende.
\nLetar du efter en patch att granska? Kolla in avsnittet ”Patchar som behöver granskas” i Django Development Dashboard.
\nVill du få din pull request granskad? Se till att Trac-flaggorna på ärendet är inställda så att ärendet visas i den kön.
\nÄ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\nAUTHORS file. At your option, submit a\nContributor License Agreement.
Har detta ett accepterat ärende på Trac? Alla bidrag kräver ett ärende om inte ändringen anses vara trivial.
Does the coding style conform to our\nguidelines? Are there any black, blacken-docs, flake8,\nisort, 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\ncomment on the pull request, have you reviewed the missing coverage in\ncontext (considering database/platform-specific limitations)?
Om ändringen påverkar Django-admin eller HTML-utdata, har accessibility testing gjorts?
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?
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.
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?
Se guiden Avveckling av en funktion.
\n