Inlämning av bidragLink to this heading#

Rättelser av stavfel och triviala dokumentationsändringarLink to this heading#

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å” ärendenLink to this heading#

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.

BidragsstilLink to this heading#

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 gemenskapenLink to this heading#

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.

Avveckling av en funktionLink to this heading#

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:

   Code

   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:

   Code

   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-projektLink to this heading#

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 JavaScriptLink to this heading#

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

OptimeringsplåsterLink to this heading#

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.

Checklista för bidragLink to this heading#

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.