Как освободить Django¶

Быстрый обзор¶

Существует три типа релизов, которые вам могут понадобиться:

• Релизы безопасности: раскрытие и устранение уязвимости. Как правило, это два или три одновременных релиза - например, 3.2.x, 4.0.x и, в зависимости от сроков, возможно, 4.1.x.
• Регулярные выпуски версий: либо финальный релиз (например, 4.1), либо обновление с исправлением ошибок (например, 4.1.1).
• Предварительные версии: например, 4.2 alpha, beta или rc.

Краткая версия действий такова:

1. Если это релиз безопасности, предварительно оповестите список рассылки безопасности за неделю до фактического релиза.
2. Вычитайте примечания к выпуску, ищите организационные и письменные ошибки. Составьте проект сообщения в блоге и объявления по электронной почте.
3. Обновите номера версий и создайте артефакты выпуска.
4. Создайте новый Release в окне администратора на djangoproject.com.
   1. Установите правильную дату, но убедитесь, что флажок is_active отключен.
   2. Загрузите артефакты (архив, колесо и контрольные суммы).
5. Проверьте подписи пакетов, убедитесь, что они могут быть установлены, и обеспечьте минимальную функциональность.
6. Загрузите новую версию(и) в PyPI.
7. Включите флаг is_active для каждого выпуска в разделе «Администратор» на djangoproject.com.
8. Опубликуйте запись в блоге и разошлите объявления по электронной почте.
9. Обновляйте номера версий после выпуска в стабильных ветвях.
10. Добавьте примечания к выпуску заглушки для следующего выпуска исправления в main и backport.

Подробностей очень много, поэтому читайте дальше.

Пререквизиты¶

Прежде чем приступить к работе, вам понадобится кое-что уточнить. Если это ваш первый релиз, вам нужно будет согласовать это с другим разработчиком, чтобы все согласовать, и написать в список рассылки Ops с запросом необходимого доступа и разрешений.

• Среда Unix с установленными этими инструментами (в алфавитном порядке):

  • удар
  • мерзавец
  • GPG
  • делать
  • человек
  • инструменты хэширования (обычно md5sum, sha1sum, и sha256sum в Linux или md5 и shasum в macOS)
  • питон

• Пара ключей GPG. Убедитесь, что закрытая часть этого ключа надежно сохранена. Общедоступную часть необходимо загрузить в вашу учетную запись на GitHub, а также на сервер Jenkins, на котором выполняется задание «подтвердить выпуск».

  Более одного ключа GPG

  Если ключ, который вы хотите использовать, не является вашим ключом подписи по умолчанию, вам нужно будет добавить -u you@example.com к каждой команде подписи GPG, показанной ниже, где you@example.com - это адрес электронной почты, связанный с ключом, который вы хотите использовать.

• Выпускается чистая виртуальная среда Python для каждой версии Django с установленными необходимыми пакетами Python:

  $ python -m pip install build twine
  

• Доступ к Django’s project on PyPI для загрузки двоичных файлов, в идеале с дополнительными правами доступа к yank a release, если это необходимо. Создайте токен в рамках проекта, следуя official documentation, и настройте свой файл $HOME/.pypirc следующим образом:

  ~/.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.
  

• Доступ к Django’s project on Transifex с ролью менеджера. Сгенерируйте токен API в user setting section и настройте свой файл $HOME/.transifexrc следующим образом:

  ~/.transifexrc¶

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

• Доступ к администратору Django на djangoproject.com в качестве «сопровождающего сайта».

• Доступ для создания записи в Django Forum - Announcements category и отправки электронных писем в список рассылки django-announce.

• Доступ к репозиторию django-security на GitHub. Помимо прочего, это обеспечивает доступ к списку рассылки предварительных уведомлений (необходим для задач подготовки выпуска безопасности).

• Доступ к проекту Django на Read the Docs.

Предрелизные задачи¶

Необходимо решить несколько вопросов еще до начала процесса выпуска. Этот процесс начинается примерно за неделю до релиза; большую часть работы можно выполнить в любое время до самого выпуска.

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

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

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

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

   $ 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. Перейдите к Add release page in the admin, создайте объект Release для окончательного выпуска, убедитесь, что поле Дата выпуска пусто, и пометьте его как неизданный. Например, при создании stable/5.2.x создайте 5.2 с пустым полем даты выпуска. Если выпуск является частью ветви LTS, отметьте его таким образом.

5. Перейдите к Add document release page in the admin, создайте новый объект DocumentRelease для английского языка для вновь созданного объекта Release. Не отмечайте это как значение по умолчанию.

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

7. Request the new classifier on PyPI. Например, Framework :: Django :: 5.2.

8. Создайте roadmap page для следующего релиза, который будет опубликован в ближайшее время. Чтобы создать новую страницу в Вики, перейдите по URL-адресу, где вы хотите создать страницу, и будет доступна кнопка «Создать эту страницу».

9. Обновите текущую ветку, находящуюся в активной разработке, и добавьте предрелизную ветку в Django release process на Trac.

10. Обновите docs/fixtures/doc_releases.json JSON-файл для djangoproject.com, чтобы люди, не имеющие доступа к рабочей базе данных, могли по-прежнему запускать обновленную копию сайта docs (example PR). Это будет объединено после окончательного выпуска.

Фактическое развертывание релиза¶

Итак, это самая интересная часть, когда мы действительно выпускаем релиз! Если вы выпускаете ** несколько релизов **, повторите эти шаги для каждого релиза.

1. Отметьте, что Jenkins имеет зеленый цвет для версий, которые вы выпускаете. Вероятно, вам не следует выпускать релиз, пока он не станет зеленым, и вы должны убедиться, что последний зеленый выпуск включает изменения, которые вы выпускаете.

2. Очистите примечания к выпуску для этого выпуска. Внесите эти изменения в main и перенесите их во все разделы, где находятся примечания к выпуску для конкретной версии.

   1. Для выпуска новой функции удалите заголовок UNDER DEVELOPMENT в верхней части примечаний к выпуску, уберите префикс Expected и при необходимости обновите дату выпуска (example commit).
   2. Для выпуска исправления удалите префикс Expected и при необходимости обновите дату выпуска для всех выпусков (example commit).

3. Выпуск всегда начинается с ветки release, поэтому вам следует убедиться, что вы используете обновленную стабильную ветку. Кроме того, у вас должна быть доступна чистая и выделенная версия виртуальной среды, которая будет выпущена. Например:

   $ git checkout stable/4.1.x
   $ git pull
   

4. Если это релиз безопасности, слейте соответствующие патчи из django-security. Перезалейте эти патчи по мере необходимости, чтобы каждый из них стал обычным коммитом в ветке релиза, а не коммитом слияния. Для этого объедините их с флагом --ff-only; например:

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

   (При этом предполагается, что security/4.1.x - это ветка в репозитории django-security, содержащая необходимые исправления безопасности для следующего выпуска серии 4.1).

   Если git отказывается сливаться с --ff-only, переключитесь на ветку security-patch и перебазируйте ее на ветку, с которой вы собираетесь слиться (git checkout security/4.1.x; git rebase stable/4.1.x), а затем переключитесь обратно и выполните слияние. Убедитесь, что сообщение о фиксации каждого исправления безопасности объясняет, что фиксация является исправлением безопасности и что за ней последует объявление (example security commit).

5. Обновите номер версии в django/__init__.py для выпуска. Пожалуйста, смотрите notes on setting the VERSION tuple ниже для получения подробной информации о VERSION (example commit).

   1. Если это предварительный выпуск пакета, также обновите классификатор находок «Статус разработки» в pyproject.toml, чтобы отразить это. Предварительный выпуск rc не должен изменять классификатор сокровищ (example commit for alpha release, example commit for beta release).
   2. В противном случае убедитесь, что для классификатора установлено значение Development Status :: 5 - Production/Stable.

Сделать релиз(ы) доступным для общественности¶

Теперь вы готовы выпустить релиз в свет. Для этого:

1. Создайте новую запись Release в поле djangoproject.com’s admin. Если это обновление системы безопасности, это следует сделать за 15 минут до объявленного времени выпуска, не раньше:

   Версия

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

   Активен

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

   LTS (длина волны)

   Включить, если релиз является частью ветви LTS.

   Даты

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

   Артефакты

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

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

3. Запустите сборку confirm-release на Jenkins для проверки файла(ов) контрольных сумм (например, используйте 4.2rc1 для https://media.djangoproject.com/pgp/Django-4.2rc1.checksum.txt).

4. Загрузите релизные пакеты на PyPI (для предварительных релизов загрузите только файл wheel):

   $ twine upload --repository django dist/*
   

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

6. Разместите свою работу и новый тег:

   $ git push
   $ git push --tags
   

7. Сделайте запись в блоге, анонсирующую релиз, прямой трансляцией.

8. При выходе новой версии (например, 4.1, 4.2) обновите стабильную версию документации по умолчанию, установив флаг is_default на True для соответствующего объекта DocumentRelease в базе данных docs.djangoproject.com (для всех остальных он автоматически установится на False); сделать это можно с помощью администратора сайта.

   Создайте новые объекты DocumentRelease для каждого языка, в котором есть запись для предыдущей версии. Обновите файл djangoproject.com’s robots.docs.txt, скопировав результат, полученный в результате выполнения команды manage_translations.py robots_txt в текущей стабильной ветке, из django-docs-translations repository. Например, при выпуске Django 4.2:

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

9. Разместите объявление о выпуске в списке рассылки django-announce и на форуме Django. Это должно содержать ссылку на сообщение в блоге с анонсом.

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

После освобождения¶

Вы почти закончили! Все, что теперь осталось сделать, это:

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

2. Добавьте релиз в Trac’s versions list, если необходимо (и сделайте его по умолчанию, изменив настройку default_version в trac.ini на code.djangoproject.com, если это финальный релиз). Новая версия X.Y должна быть добавлена после выхода альфа-версии, а версия по умолчанию должна быть обновлена после выхода «dot zero».

3. Если бы это был окончательный выпуск:

   1. Обновите текущую стабильную ветку и удалите предрелизную ветку в Django release process on Track.
   2. Djangoproject.com обновление загрузки страницы (example PR).

4. Если это был выпуск безопасности, обновите Архив вопросов безопасности с подробным описанием устраненных проблем.

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. Просмотрите diff перед отправкой и избегайте внесения изменений в файлы .po без каких-либо новых переводов (example commit).

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

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

6. Если это был предварительный выпуск rc, запросите переводы для предстоящего выпуска в разделе Django Forum - Internationalization category.

Примечания по установке кортежа VERSION¶

Отчетность о версии в Django контролируется кортежем VERSION в django/__init__.py. Это кортеж из пяти элементов, элементами которого являются:

1. Основная версия.
2. Незначительная версия.
3. Микро версия.
4. Статус – может быть одним из «alpha», «beta», «rc» или «final».
5. Номер серии, для пакетов альфа/бета/RC, которые запускаются последовательно (позволяя, например, «beta 1», «beta 2» и т.д.).

Для финального релиза статус всегда «final», а номер серии всегда 0. Номер серии 0 со статусом «альфа» будет представлен как «пре-альфа».

Некоторые примеры:

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