Så här släpper du DjangoLink to this heading#

ÖversiktLink to this heading#

Det finns tre typer av releaser som du kan behöva göra:

• Säkerhetsreleaser: avslöja och åtgärda en sårbarhet. Detta innebär i allmänhet två eller tre samtidiga releaser - t.ex. 3.2.x, 4.0.x och, beroende på tidpunkt, kanske en 4.1.x.

• Regelbundna versionsreleaser: antingen en slutlig version (t.ex. 4.1) eller en buggfixuppdatering (t.ex. 4.1.1).

• Förhandsversioner: t.ex. 4.2 alpha, beta eller rc.

Den korta versionen av de inblandade stegen är:

1. Om det rör sig om en säkerhetsrelease ska du meddela säkerhetsdistributionslistan en vecka före den faktiska releasen.

2. Korrekturläsa versionsinformation, leta efter organisations- och skrivfel. Skriva ett blogginlägg och ett e-postmeddelande.

3. Uppdatera versionsnummer och skapa artefakter för releasen.

4. Skapa den nya Release i administratören på djangoproject.com.

   1. Ange rätt datum men se till att flaggan is_active är inaktiverad.

   2. Ladda upp artefakterna (tarball, wheel och checksummor).

5. Verifiera paketens signaturer, kontrollera om de kan installeras och säkerställa minimal funktionalitet.

6. Ladda upp den nya versionen/versionerna till PyPI.

7. Aktivera flaggan is_active för varje utgåva i administratören på djangoproject.com.

8. Publicera blogginlägget och skicka ut e-postmeddelandena.

9. Uppdatera versionsnummer efter release i stabila grenar.

10. Lägg till stub versionsinformation för nästa patch release i main och backport.

Det finns många detaljer, så läs gärna vidare.

FörutsättningarLink to this heading#

Du behöver några saker innan du sätter igång. Om det här är din första release måste du samordna med en annan releaser för att få allt detta klart, och skriva till Ops e-postlista och begära nödvändig åtkomst och behörigheter.

• En Unix-miljö med dessa verktyg installerade (i alfabetisk ordning):

  • bash (version 4.0+)

  • git

  • GPG

  • göra

  • man

  • hashingverktyg (vanligtvis md5sum, sha1sum och sha256sum på Linux, eller md5 och shasum på macOS)

  • python

• Ett GPG-nyckelpar. Lagra den privata delen säkert och skydda den med en lösenfras. Den offentliga delen måste laddas upp till ditt GitHub-konto.

• En ren virtuell Python-miljö (Python 3.10+, pip 26.1+) för att bygga artefakter.

• Åtkomst till Djangos projekt på PyPI för att ladda upp binärfiler, helst med ytterligare behörighet att vid behov dra tillbaka en utgåva. Se till att ditt PyPI-konto endast använder WebAuthn-baserade autentiseringsfaktorer, inte TOTP (engångskoder). Skapa en API-token enligt den officiella dokumentationen och konfigurera sedan filen $HOME/.pypirc så här:

  Ini

  [distutils]
    index-servers =
      pypi
      django
  
  [pypi]
    username = __token__
    password = # User-scoped or project-scoped token, to set as the default.
  
  [django]
    repository = https://upload.pypi.org/legacy/
    username = __token__
    password = # A project token.
  

• Åtkomst till Djangos projekt på Transifex, med rollen Manager. Skapa en API-token i avsnittet för användarinställningar och konfigurera sedan filen $HOME/.transifexrc så här:

  Ini

  [https://www.transifex.com]
    rest_hostname = https://rest.api.transifex.com
    token = # API token
  

• Tillgång till Django-administratören på djangoproject.com som ”Site maintainer”.

• Behörighet att skapa ett inlägg i Django Forum – kategorin Announcements och att skicka e-post till sändlistan django-announce.

• Tillgång till django-security repo i GitHub. Detta ger bland annat tillgång till distributionslistan för föranmälningar (behövs för förberedelser inför säkerhetsreleaser).

• Åtkomst till Django-projektet på Read the Docs.

Uppgifter före lanseringLink to this heading#

Några saker måste tas om hand innan man ens påbörjar releaseprocessen. Det här börjar ungefär en vecka före lanseringen; det mesta kan göras när som helst fram till den faktiska lanseringen.

Frysa funktioner för uppgifterLink to this heading#

1. Ta bort tomma avsnitt från versionsinformation (exempel commit).

2. Bygg versionsinformation lokalt och läs dem. Gör eventuella nödvändiga ändringar för att förbättra flödet eller fixa grammatiken (exempel commit).

3. Skapa en ny stabil gren från main. Se till att hämta och uppdatera upstream till den senaste versionen. Till exempel när Django 5.2 funktionsfryses:

   Shell

   $ git fetch upstream
   $ git checkout -b stable/5.2.x upstream/main
   $ git push upstream -u stable/5.2.x:stable/5.2.x
   

   Samtidigt uppdaterar du variabeln django_next_version i docs/conf.py på den stabila utgivningsgrenen så att den pekar på den nya utvecklingsversionen. Till exempel, när du skapar stable/5.2.x, sätt django_next_version till '6.0' på den nya stabila grenen (example commit).

4. Skapa poster av typen Release för nästa version i administrationen på djangoproject.com. Lägg till en för varje milstolpe (alpha, beta, rc och final) och låt is active vara avmarkerad för att markera dem som ej utgivna. Ange måldatum enligt överenskommen planering och sätt LTS-flaggan om den är tillämplig. Vägsidan för X.Y kommer att finnas på /download/X.Y/roadmap/.

   När du till exempel skapar stable/5.2.x lägger du till poster av typen Release för 6.0a1, 6.0b1, 6.0rc1 och 6.0. Färdplanen för 6.0 kan sedan granskas på https://www.djangoproject.com/download/6.0/roadmap/.

5. Gå till sidan `Lägg till dokumentutgåva i admin`__, skapa ett nytt DocumentRelease-objekt för det engelska språket för det nyskapade Release-objektet. Markera inte detta som standard.

6. Lägg till den nya grenen på Read the Docs. Eftersom de automatiskt genererade versionsnamnen (”stable-A.B.x”) skiljer sig från versionsnamnen som används i Read the Docs (”A.B.x”), uppdaterar du Read the Docs-konfigurationen för versionen så att den pekar på sluggen A.B.x och anger den som aktiv. Se fler detaljer.

7. Skapa en PR på PyPI som föreslår den nya Trove-klassificeringen. Exempelvis Framework :: Django :: 5.2.

8. Uppdatera den aktuella grenen under aktiv utveckling och lägg till förutgivningsgrenen i Djangos releaseprocess på Trac.

9. Uppdatera docs/fixtures/doc_releases.json JSON-fixturen för djangoproject.com, så att personer utan tillgång till produktions-DB:n fortfarande kan köra en uppdaterad kopia av dokumentsidan (exempel PR). Detta kommer att slås samman efter den slutliga utgåvan.

Att faktiskt rulla ut releasenLink to this heading#

OK, nu kommer den roliga delen, när vi faktiskt skickar ut en release! Om du ska skicka ut flera releaser, upprepa dessa steg för varje release.

1. Kontrollera att `Jenkins`__ är grön för den eller de versioner du släpper. Du bör förmodligen inte publicera en release förrän den är grön, och du bör se till att den senaste gröna körningen innehåller de ändringar som du publicerar.

2. Städa upp i versionsinformation för denna version. Gör dessa ändringar i main och backportera till alla grenar där versionsnoterna för en viss version finns.

   1. För en funktionsutgåva, ta bort rubriken UNDER DEVELOPMENT högst upp i utgåvan, ta bort prefixet Expected och uppdatera utgivningsdatumet, om det behövs (exempel commit).

   2. För en patchversion, ta bort prefixet Expected och uppdatera utgivningsdatumet för alla versioner, om nödvändigt (exempel commit).

3. Återskapa en ny, särskild virtuell miljö för releaseverktygen med en väntetid:

   Shell

   $ python -m pip install build twine --uploaded-prior-to=P7D
   

4. En release börjar alltid från en releasegren, så du bör säkerställa att du är på en uppdaterad stabil gren. Till exempel:

   Shell

   $ git checkout stable/4.1.x
   $ git pull
   

5. Om detta är en säkerhetsrelease, slå samman lämpliga korrigeringar från django-security. Basera om dessa korrigeringar efter behov för att göra var och en till en vanlig commit på release-grenen snarare än en merge commit. För att säkerställa detta, sammanfoga dem med flaggan --ff-only; till exempel:

   Shell

   $ git checkout stable/4.1.x
   $ git merge --ff-only security/4.1.x
   

   (Detta förutsätter att security/4.1.x är en gren i repot django-security som innehåller de nödvändiga säkerhetsuppdateringarna för nästa utgåva i 4.1-serien)

   Om git vägrar att slå samman med --ff-only, byt till security-patch grenen och rebasera den på den gren du är på väg att slå samman den med (git checkout security/4.1.x; git rebase stable/4.1.x) och byt sedan tillbaka och gör sammanslagningen. Se till att commit-meddelandet för varje säkerhetsfix förklarar att commit är en säkerhetsfix och att ett tillkännagivande kommer att följa (exempel på säkerhetsfix).

6. Uppdatera versionsnumret i django/__init__.py för utgåvan. Vänligen se notes on setting the VERSION tuple nedan för detaljer om VERSION (example commit).

   1. Om det här är ett paket som släppts före utgivningen ska du även uppdatera trove-klassificeraren ”Development Status” i pyproject.toml för att återspegla detta. En rc-förutgåva bör inte ändra trove-klassificeringen (example commit for alpha release, example commit for beta release).

   2. Annars, se till att klassificeraren är inställd på Development Status :: 5 - Produktion/Stabil.

Göra utgivningen tillgänglig för allmänhetenLink to this heading#

Nu är du redo att faktiskt skicka ut pressmeddelandet. För att göra detta:

1. Skapa en ny post för Release i administrationen på djangoproject.com. Om detta är en säkerhetsrelease ska det göras 15 minuter före den aviserade releasetiden, inte tidigare:

   Version

   Måste överensstämma med versionsnumret enligt definitionen i tarbollen (django-<version>.tar.gz). Exempelvis ”5.2”, ”4.1.1” eller ”4.2rc1”.

   Är aktiv

   Ställ in på False tills releasen är helt publicerad (sista steget).

   LTS

   Aktivera om utgåvan är en del av en LTS-gren.

   Datum

   Ställ in utgivningsdatumet till idag. Den här utgåvan kommer inte att publiceras förrän is_active är aktiverat.

   Artefakter

   Ladda upp filerna tarball (django-<version>.tar.gz), wheel (django-<version>-py3-none-any.whl) och checksum (django-<version>.checksum.txt.asc) som skapades tidigare.

2. Testa att release-paketen installeras korrekt med hjälp av pip. Här är en enkel metod (den här testar bara att binärerna är tillgängliga, att de installeras korrekt och att migreringar och utvecklingsservern startar, men den kommer att upptäcka dumma misstag): https://code.djangoproject.com/wiki/ReleaseTestNewVersion.

3. Kör `confirm-release`__ build på Jenkins för att verifiera checksummefilerna (använd t.ex. 4.2rc1 för https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).

4. Skapa en ny token för den här releasen på PyPI och lagra den i .pypirc enligt ovan.

5. Ladda upp releasepaketen till PyPI:

   Shell

   $ twine upload --repository django dist/*
   

6. Återkalla tokenen som du nyss skapade på PyPI.

7. Uppdatera den nyskapade Release i administratören i djangoproject.com och aktivera flaggan is_active.

8. Tryck på ditt arbete och den nya taggen:

   Shell

   $ git push
   $ git push --tags
   

9. Gör blogginlägget som tillkännager lanseringen live.

10. För en ny versionsutgåva (t.ex. 4.1, 4.2), uppdatera den stabila standardversionen av dokumenten genom att vända flaggan is_default till True på lämpligt DocumentRelease-objekt i databasen docs.djangoproject.com (detta kommer automatiskt att vända den till False för alla andra); du kan göra detta med webbplatsens administratör.

    Skapa nya DocumentRelease-objekt för varje språk som har en post för den föregående utgåvan. Uppdatera djangoproject.com:s `robots.docs.txt`__-fil genom att kopiera resultatet som genereras genom att köra kommandot manage_translations.py robots_txt i den aktuella stabila grenen från `django-docs-translations repository`__. Till exempel, när du släpper Django 4.2:

    Shell

    $ git checkout stable/4.2.x
    $ git pull
    $ python manage_translations.py robots_txt
    

11. Skicka meddelandet om utgåvan till e-postlistan django-announce och Django Forum. Detta bör innehålla en länk till tillkännagivandets blogginlägg.

12. Om detta är en säkerhetsrelease ska CVE-metadata publiceras. (checklist-appen genererar JSON för detta.)

    Shell

    $ cve publish <cve-number> --cve-json-file <path-to-file>
    

13. Om detta är en säkerhetsrelease ska du skicka ett separat e-postmeddelande till oss-security@lists.openwall.com. Ange ”Django” samt CVE-id:n i ämnesraden. Meddelandetexten ska innehålla information om sårbarheten, till exempel texten från tillkännagivandets blogginlägg. Inkludera en länk till blogginlägget.

Efter lanseringLink to this heading#

Du är nästan klar! Allt som återstår att göra nu är:

1. Om detta inte är en förhandsutgåva, uppdatera VERSION tupeln i django/__init__.py igen, öka till vad nästa förväntade utgåva kommer att vara. Till exempel, efter att ha släppt 4.1.1, uppdatera VERSION till VERSION = (4, 1, 2, 'alpha', 0) (example commit).

2. Om detta var en alfautgåva:

   1. Lägg till versionen för funktionsreleasen i Tracs versionslista.

   2. Skapa en ny säkerhetsgren från den nyss skapade stabila grenen. Se till att hämta och uppdatera upstream till senaste version. Exempelvis efter alfautgåvan 5.2:

      Shell

      $ git fetch upstream
      $ git checkout -b security/5.2.x upstream/stable/5.2.x
      $ git push origin -u security/5.2.x:security/5.2.x
      

3. Om detta var en slutlig version:

   1. Uppdatera inställningen default_version i filen trac.ini för code.djangoproject.com (exempel-PR).

   2. Uppdatera den aktuella stabila grenen och ta bort förutgivningsgrenen i Djangos releaseprocess på Trac.

   3. Uppdatera djangoproject.com:s nedladdningssida (exempel PR).

   4. Hantera de äldre versioner som når End-Of-Mainstream- och/eller End-Of-Life-stöd när denna slutliga release publiceras:

      1. Säkerställ att EOL-versionerna nämns i blogginlägget. Se exempel på tillkännagivande.

      2. Skapa en tagg för den stabila EOL-grenen och ta bort den stabila grenen. Kontrollera och använd hjälpskriptet scripts/archive_eol_stable_branches.py.

4. Om detta var en säkerhetsrelease, uppdatera Arkiv över säkerhetsfrågor med detaljer om de problem som åtgärdats.

5. Om detta var en förhandsversion måste översättningskatalogerna uppdateras:

   1. Skapa en ny gren från den nyligen utgivna stabila grenen:

      Shell

      $ git checkout stable/A.B.x
      $ git checkout -b update-translations-catalog-A.B.x
      

   2. Se till att releaseprogrammets dedikerade virtuella miljö är aktiverad och kör följande:

      Shell

      $ cd django
      $ django-admin makemessages -l en --domain=django
      processing locale en
      $ django-admin makemessages -l en --domain=djangojs
      processing locale en
      

   3. Gör en pull request mot motsvarande stabila gren och slå samman när den har godkänts.

   4. Vidarebefordra de uppdaterade källöversättningarna till huvud-grenen (exempel commit).

6. Om detta var en förutgåva av typen alpha ska du samordna med underhållaren av asgiref för att avgöra när minimiversionen ska höjas före den slutliga releasen. För backporten lägger du till en övre gräns för nästa huvudversion (exempelcommits: main, backport).

7. Om detta var en förutgåva av typen rc ska du efterlysa översättningar för den kommande releasen i Django Forum – kategorin Internationalization.

Anvisningar för inställning av VERSION-tupelnLink to this heading#

Djangos versionsrapportering styrs av tupeln VERSION i django/__init__.py. Detta är en tupel med fem element, vars element är:

1. Större version.

2. Mindre version.

3. Mikroversion.

4. Status – kan vara en av ”alpha”, ”beta”, ”rc” eller ”final”.

5. Serienummer, för alfa/beta/RC-paket som körs i sekvens (tillåter t.ex. ”beta 1”, ”beta 2”, etc.).

För en slutlig version är statusen alltid ”final” och serienumret är alltid 0. Ett serienummer på 0 med statusen ”alpha” kommer att rapporteras som ”pre-alpha”.

Några exempel:

• (4, 1, 1, "final", 0) → ”4.1.1”

• (4, 2, 0, "alpha", 0) → ”4.2 pre-alpha”

• (4, 2, 0, "beta", 1) → ”4.2 beta 1”