Обзор¶

There are three types of releases that you might need to make:

• Security releases: disclosing and fixing a vulnerability. This’ll generally involve two or three simultaneous releases – e.g. 3.2.x, 4.0.x, and, depending on timing, perhaps a 4.1.x.

• Regular version releases: either a final release (e.g. 4.1) or a bugfix update (e.g. 4.1.1).

• Pre-releases: e.g. 4.2 alpha, beta, or rc.

The short version of the steps involved is:

1. If this is a security release, pre-notify the security distribution list one week before the actual release.

2. Proofread the примечания к выпуску, looking for organization and writing errors. Draft a blog post and email announcement.

3. Обновите номера версий и создайте артефакты выпуска.

4. Создайте новый Release в администраторе на djangoproject.com.

   1. Установите правильную дату, но убедитесь, что флаг is_active отключен.

   2. Загрузите артефакты (архив, колесо и контрольные суммы).

5. Verify package(s) signatures, check if they can be installed, and ensure minimal функцияality.

6. Upload the new version(s) to PyPI.

7. Включите флаг is_active для каждого выпуска в администраторе на djangoproject.com.

8. Post the blog entry and send out the email announcements.

9. Обновить номера версий после выпуска в стабильных ветках.

10. Добавьте примечания к заглушке для следующего выпуска патча в main и backport.

There are a lot of details, so please read on.

Prerequisites¶

You’ll need a few things before getting started. If this is your first release, you’ll need to coordinate with another releaser to get all these things lined up, and write to the Ops mailing list requesting the required access and permissions.

• A Unix environment with these tools installed (in alphabetical order):

  • bash

  • git

  • GPG

  • make

  • man

  • hashing tools (typically md5sum, sha1sum, and sha256sum on Linux, or md5 and shasum on macOS)

  • python

• A GPG key pair. Ensure that the private part of this key is securely stored. The public part needs to be uploaded to your GitHub account, and also to the Jenkins server running the «confirm release» job.

  More than one GPG key

  If the key you want to use is not your default signing key, you’ll need to add -u you@example.com to every GPG signing command shown below, where you@example.com is the email address associated with the key you want to use.

• Чистая виртуальная среда Python (Python 3.9+) для создания артефактов со следующими необходимыми пакетами Python:

  $ python -m pip install build twine
  

• Access to Django’s project on PyPI to upload binaries, ideally with extra permissions to yank a release if necessary. Create a project-scoped token following the official documentation and set up your $HOME/.pypirc file like this:

  ~/.pypirc¶

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

• Access to Django’s project on Transifex, with a Manager role. Generate an API Token in the user setting section and set up your $HOME/.transifexrc file like this:

  ~/.transifexrc¶

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

• Access to the Django admin on djangoproject.com as a «Site maintainer».

• Доступ для создания сообщения в категории Форум Django - Объявления и отправки электронных писем в список рассылки django-announce.

• Access to the django-security repo in GitHub. Among other things, this provides access to the pre-notification distribution list (needed for security release preparation tasks).

• Доступ к проекту Django на странице Чтение документации.

Pre-release tasks¶

A few items need to be taken care of before even beginning the release process. This stuff starts about a week before the release; most of it can be done any time leading up to the actual release.

Задачи по заморозке функций¶

1. Удалите пустые разделы из примечаний к выпуску (example commit).

2. Создайте примечания к выпуску локально и прочитайте их. Внесите все необходимые изменения, чтобы улучшить поток или исправить грамматику (example commit).

3. Создайте новую стабильную ветку из main. Обязательно скачайте и обновите upstream до последней версии. Например, при зависании функции Django 5.2:

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

   В то же время обновите переменную django_next_version в docs/conf.py в ветке стабильной версии, чтобы она указывала на новую версию разработки. Например, при создании stable/5.2.x установите django_next_version в '6.0' в новой стабильной ветке (example commit).

4. Создайте записи Release для следующей версии в admin`__ на djangoproject.com. Добавьте по одному для каждой вехи (альфа, бета, версия RC и финальная версия), оставив активно неустановленным, чтобы пометить их как невыпущенные. Установите целевые даты в соответствии с согласованным графиком и установите флаг LTS, если применимо. Страница дорожной карты X.Y будет доступна по адресу /download/X.Y/roadmap/.

   Например, при создании stable/5.2.x добавьте записи Release для 6.0a1, 6.0b1, 6.0rc1 и 6.0. Дорожную карту «6.0» можно затем просмотреть по адресу https://www.djangoproject.com/download/6.0/roadmap/.

5. Перейдите на страницу «Добавить выпуск документа» в админке, создайте новый объект «DocumentRelease» для английского языка для вновь созданного объекта «Release». Не отмечайте это как значение по умолчанию.

6. Добавьте новую ветку Читать документы. Поскольку автоматически сгенерированные имена версий («stable-A.B.x») отличаются от имен версий, используемых в Read the Docs («A.B.x»), обновите конфигурацию Read the Docs для версии, чтобы она указывала на пул A.B.x, и установите его как активный. Подробнее см..

7. Создайте PR на PyPI, предложив новый классификатор Trove. Например Framework::Django:::5.2.

8. Update the current branch under active development and add pre-release branch in the Django release process on Trac.

9. Обновите JSON-фикстур docs/fixtures/doc_releases.json для djangoproject.com, чтобы люди, не имеющие доступа к рабочей базе данных, могли по-прежнему запускать актуальную копию сайта документации (пример PR <https://github.com/django/djangoproject.com/pull/1446>`__). Это будет объединено после окончательного выпуска.

Actually rolling the release¶

OK, this is the fun part, where we actually push out a release! If you’re issuing multiple releases, repeat these steps for each release.

1. Check `Jenkins`__ is green for the version(s) you’re putting out. You probably shouldn’t issue a release until it’s green, and you should make sure that the latest green run includes the changes that you are releasing.

2. Cleanup the примечания к выпуску for this release. Make these changes in main and backport to all branches where the примечания к выпуску for a particular version are located.

   1. For a feature release, remove the UNDER DEVELOPMENT header at the top of the примечания к выпуску, remove the Expected prefix and update the release date, if necessary (example commit).

   2. For a patch release, remove the Expected prefix and update the release date for all releases, if necessary (example commit).

3. A release always begins from a release branch, so you should make sure you’re on an up-to-date stable branch. Also, you should have available a clean and dedicated virtual environment per version being released. For example:

   $ git checkout stable/4.1.x
   $ git pull
   

4. If this is a security release, merge the appropriate patches from django-security. Rebase these patches as necessary to make each one a plain commit on the release branch rather than a merge commit. To ensure this, merge them with the --ff-only flag; for example:

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

   (This assumes security/4.1.x is a branch in the django-security repo containing the necessary security patches for the next release in the 4.1 series.)

   If git refuses to merge with --ff-only, switch to the security-patch branch and rebase it on the branch you are about to merge it into (git checkout security/4.1.x; git rebase stable/4.1.x) and then switch back and do the merge. Make sure the commit message for each security fix explains that the commit is a security fix and that an announcement will follow (example security commit).

5. Update the version number in django/__init__.py for the release. Please see notes on setting the VERSION tuple below for details on VERSION (example commit).

   1. Если это предварительная версия пакета, также обновите классификатор сокровищ «Состояние разработки» в pyproject.toml, чтобы отразить это. Предварительная версия rc не должна менять классификатор trove (пример фиксации для альфа-версии, пример фиксации для бета-версии).

   2. Otherwise, make sure the classifier is set to Development Status :: 5 - Production/Stable.

$ PGP_KEY_ID=<key-id> PGP_KEY_URL=<key-url> DEST_FOLDER=~/releases scripts/do_django_release.py

$ VERSION=5.2.1 scripts/test_new_version.sh

$ VERSION=5.2.1 scripts/confirm_release.sh

Making the release(s) available to the public¶

Now you’re ready to actually put the release out there. To do this:

1. Создайте новую запись Release в администраторской панели djangoproject.com <https://www.djangoproject.com/admin/releases/release/add/>`_. Если это выпуск безопасности, это следует сделать за 15 минут до объявленного времени выпуска, не раньше:

   Версия

   Должен соответствовать номеру версии, определенному в архиве (django-<версия>.tar.gz). Например: «5.2», «4.1.1» или «4.2rc1».

   Активен

   Установите значение False до тех пор, пока выпуск не будет полностью опубликован (последний шаг).

   LTS

   Включите, если выпуск является частью ветки LTS.

   Даты

   Установите дату выпуска на сегодня. Этот выпуск не будет опубликован, пока не будет включен is_active.

   Артефакты

   Загрузите файлы tarball (django-<версия>.tar.gz), колесо (django-<версия>-py3-none-any.whl) и файлы контрольной суммы (django-<версия>.checksum.txt.asc), созданные ранее.

2. Проверьте правильность установки пакетов выпуска с помощью pip. Вот один простой метод (он просто проверяет, что двоичные файлы доступны, правильно ли они установлены, а также запускаются миграции и сервер разработки, но он выявляет глупые ошибки): https://code.djangoproject.com/wiki/ReleaseTestNewVersion.

3. Run the `confirm-release`__ build on Jenkins to verify the checksum file(s) (e.g. use 4.2rc1 for https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).

4. Загрузите пакеты релизов в PyPI:

   $ twine upload --repository django dist/*
   

5. Обновите вновь созданный Release в администраторской панели djangoproject.com и включите флаг is_active.

6. Push your work and the new tag:

   $ git push
   $ git push --tags
   

7. Make the blog post announcing the release live.

8. For a new version release (e.g. 4.1, 4.2), update по умолчанию stable version of the docs by flipping the is_default flag to True on the appropriate DocumentRelease object in the docs.djangoproject.com database (this will automatically flip it to False for all others); you can do this using the site’s admin.

   Create new DocumentRelease objects for each language that has an entry for the previous release. Update djangoproject.com’s `robots.docs.txt`__ file by copying the result generated from running the command manage_translations.py robots_txt in the current stable branch from the `django-docs-translations repository`__. For example, when releasing Django 4.2:

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

9. Post the release announcement to the django-announce mailing list and the Django Forum. This should include a link to the announcement blog post.

10. Если это выпуск безопасности, отправьте отдельное электронное письмо на адрес oss-security@lists.openwall.com. Укажите описательную тему, например «Django», а также название проблемы из примечаний к выпуску (включая идентификатор CVE). Тело сообщения должно включать сведения об уязвимости, например текст объявления в блоге. Включите ссылку на сообщение в блоге с объявлением.

Post-release¶

You’re almost done! All that’s left to do now is:

1. Если это не предварительная версия, обновите кортеж VERSION в django/__init__.py еще раз, увеличивая значение до следующего ожидаемого выпуска. Например, после выпуска 4.1.1 обновите VERSION до VERSION = (4, 1, 2, 'alpha', 0) (example commit).

2. Если бы это был альфа-релиз:

   1. Добавьте версию выпуска функции в список версий Trac.

   2. Создайте новую ветку безопасности из только что вырезанной стабильной ветки. Обязательно скачайте и обновите upstream до последней версии. Например, после альфа-версии 5.2:

      $ 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. If this was a final release:

   1. Обновите настройку default_version в файле trac.ini code.djangoproject.com (пример PR).

   2. Update the current stable branch and remove the pre-release branch in the Django release process on Trac.

   3. Update djangoproject.com’s download page (example PR).

   4. Обработайте более старые версии, которые достигнут поддержки End-Of-Mainstream и/или End-Of-Life, когда будет опубликован этот финальный выпуск:

      1. Убедитесь, что версии EOL упомянуты в сообщении блога. Пример.

      2. Создайте тег для стабильной ветки EOL и удалите стабильную ветку. Проверьте и используйте помощник scripts/archive_eol_stable_branches.py.

4. If this was a security release, update Архив проблем безопасности with details of the issues addressed.

5. Если это был предварительный выпуск, необходимо обновить каталоги переводов:

   1. Создайте новую ветку из недавно выпущенной стабильной ветки:

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

   2. Убедитесь, что выделенная виртуальная среда выпуска включена, и выполните следующее:

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

   3. Просмотрите разницу перед отправкой и избегайте внесения изменений в файлы .po без каких-либо новых переводов (example commit).

   4. Сделайте запрос на включение соответствующей стабильной ветки и выполните слияние после одобрения.

   5. Перенаправить обновленные исходные переводы в ветку main (example commit).

6. Если это была предварительная версия rc, запросите переводы для предстоящего релиза в категории ``Django Forum - Интернационализация» <https://forum.djangoproject.com/c/internals/i18n/14>`_.

Notes on setting the VERSION tuple¶

Django’s version reporting is controlled by the VERSION tuple in django/__init__.py. This is a five-element tuple, whose elements are:

1. Major version.

2. Minor version.

3. Micro version.

4. Status – can be one of «alpha», «beta», «rc» or «final».

5. Series number, for alpha/beta/RC packages which run in sequence (allowing, for example, «beta 1», «beta 2», etc.).

For a final release, the status is always «final» and the series number is always 0. A series number of 0 with an «alpha» status will be reported as «pre-alpha».

Some examples:

• (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»