Как устроен Django? ¶
В этом документе объясняется, как создается релиз Django.
Пожалуйста, обновляйте эти инструкции, если вы вносите какие-либо изменения! Главное здесь - быть описательным, а не предписывающим, поэтому не стесняйтесь упрощать или вносить другие изменения в процедуру, но затем обновите этот документ соответствующим образом!
Предварительный просмотр ¶
Возможно, вам потребуется создать три разных типа сообщений:
- Публикации по безопасности: объявление и устранение уязвимости. Обычно это включает две или три одновременных публикации - например. 1.5.x, 1.6.x и, в зависимости от времени, возможно 1.7 alpha / beta / rc.
- Нормальные выпуски версии: либо финальный выпуск (например, 1.5), либо исправляющее обновление (например, 1.5.1).
- Препринты: напр. 1.6 альфа, бета или RC.
Краткая версия следующих шагов:
- Если это публикация по безопасности, предварительно уведомите список рассылки по безопасности за неделю до фактической публикации.
- Вычитайте примечания к выпуску, особенно в отношении их организации и формулировок. Напишите черновик сообщения в блоге и рекламное письмо.
- Обновите номера версий и создайте пакеты выпуска.
- Отправьте пакет (ы) на сервер
djangoproject.com
. - Отправьте новые версии на сервер PyPI.
- Объявите новую версию в интерфейсе администрирования
djangoproject.com
. - Опубликуйте сообщение в блоге и отправьте объявление по электронной почте.
- Обновите номера версий после публикации.
Подробностей много, держитесь!
Предпосылки ¶
Перед тем, как начать, вам нужно сделать несколько вещей:
Ключ GPG. Если ключ, который вы хотите использовать, не является вашим ключом подписи по умолчанию, вам нужно будет добавить к каждой команде подписи GPG ниже, где - адрес электронной почты, связанный с ключом, который вы собираетесь использовать.
-u [email protected]
[email protected]
Установка некоторых необходимых пакетов Python
$ python -m pip install wheel twine
Доступ к учетной записи Django на PyPI. Создайте файл с вашей аутентификационной информацией:
[pypi] username:YourUsername password:YourPassword
Доступ к серверу
djangoproject.com
для отправки на него файлов.Доступ к административному интерфейсу
djangoproject.com
в качестве «сопровождающего сайта».Право публикации на
django-announce
.Если это публикация по безопасности, получите доступ к списку рассылки предварительного уведомления.
Если это ваш первый выпуск, вам нужно будет координировать свои действия с другим выпускающим, чтобы согласовать все эти вещи.
Предварительные задачи ¶
О некоторых вещах нужно позаботиться еще до начала процесса выпуска. Это начинается примерно за неделю до релиза; большую часть этого можно сделать в любое время до самого релиза:
Если это выпуск безопасности, отправьте предварительное уведомление за неделю до выпуска. Шаблон для этого письма и список получателей находятся в частной
django-security
вики GitHub. BCC получатели предварительного уведомления. Подпишите электронное письмо ключом, который вы будете использовать для выпуска, и включите идентификаторы CVE (запрашиваемые у поставщика: djangoproject, продукт: django) и исправления для каждой исправляемой проблемы. Также уведомите django-announce о предстоящем выпуске системы безопасности.По мере приближения выпуска смотрите Trac, чтобы убедиться, что для предстоящего выпуска не осталось никаких блокировщиков выпуска.
Обратитесь к другим коммиттерам, чтобы убедиться, что у них нет незафиксированных изменений для выпуска.
Просмотрите примечания к выпуску, которые также включают онлайн-версию, на предмет неработающих ссылок или синтаксических ошибок reST и убедитесь, что дата примечаний к выпуску верна.
Дважды проверьте, что в примечаниях к выпуску указаны сроки прекращения поддержки любых API, отмеченных как устаревшие, и что в них упоминаются любые изменения в поддержке версии Python.
Еще раз проверьте, есть ли в указателе примечаний к выпуску ссылка на примечания к новому выпуску; это будет в
docs/releases/index.txt
.Если это функциональный выпуск, убедитесь, что переводы из Transifex были интегрированы. Обычно это делает отдельный менеджер переводов, а не релизер, но вот шаги. Если у вас есть учетная запись на Transifex:
$ python scripts/manage_translations.py fetch
а затем зафиксируйте измененные / добавленные файлы (как .po, так и .mo). Иногда возникают ошибки проверки, которые необходимо отладить, поэтому не выполняйте эту задачу непосредственно перед тем, как потребуется выпуск.
Обновите страницу руководства django-admin :
$ cd docs $ make man $ man _build/man/django-admin.1 # do a quick sanity check $ cp _build/man/django-admin.1 man/django-admin.1
а затем зафиксируйте измененную страницу руководства.
Если это альфа-версия новой серии, создайте новую стабильную ветку из master. Например, при выпуске Django 3.1:
$ git checkout -b stable/3.1.x origin/master $ git push origin -u stable/3.1.x:stable/3.1.x
Если это выпуск новой серии с нулевой точкой, создайте новую ветку из текущей стабильной ветки в репозитории django-docs-translations . Например, при выпуске Django 2.2:
$ git checkout -b stable/2.2.x origin/stable/2.1.x $ git push origin stable/2.2.x:stable/2.2.x
Подготовка к публикации ¶
Напишите сообщение в блоге с объявлением о публикации. Вы можете написать его на сайте администрирования, отметив его как неактивное. Вот несколько примеров: Пример объявления о выпуске системы безопасности , например, обычное публикуемое объявление , предварительная публикация образца объявления .
Собственно накатил релиз ¶
Хорошо, это самая интересная часть, когда мы выпускаем релиз!
Убедитесь, что Дженкинс зеленый для версий, которые вы выпускаете. Вероятно, не стоит выпускать релиз, пока он не станет зеленым.
Релиз всегда начинается с ветки релиза, поэтому вы должны быть уверены, что находитесь в стабильной ветке и обновлены. Например:
$ git checkout stable/1.5.x $ git pull
Если это выпуск безопасности, слейте соответствующие исправления из
django-security
. При необходимости измените базу этих исправлений, чтобы сделать каждый из них простой фиксацией в ветке выпуска, а не фиксацией слияния. Для этого объедините их с--ff-only
флагом; например:$ git checkout stable/1.5.x $ git merge --ff-only security/1.5.x
(Предполагается,
security/1.5.x
что это ветка вdjango-security
репозитории, содержащая необходимые исправления безопасности для следующего выпуска серии 1.5.)Если git отказывается объединяться
--ff-only
, переключитесь на ветку патча безопасности и переустановите его в ветке, в которую вы собираетесь объединить ( ), а затем переключитесь обратно и выполните слияние. Убедитесь, что сообщение о фиксации для каждого исправления безопасности объясняет, что фиксация является исправлением безопасности и что за ним последует объявление ( например, фиксация безопасности ).git checkout security/1.5.x; git rebase stable/1.5.x
Для выпуска функции удалите заголовок вверху заметок о выпуске и добавьте дату выпуска в следующей строке. Для выпуска патча замените датой выпуска. Сделайте это изменение во всех ветках, где находятся примечания к выпуску для конкретной версии.
UNDER DEVELOPMENT
*Under Development*
Обновите номер версии
django/__init__.py
для выпуска. Пожалуйста , смотрите примечания по установке VERSION кортеж ниже подробную информацию оVERSION
.Если это предварительный пакет, обновите классификатор «Статус разработки»,
setup.cfg
чтобы отразить это. В противном случае убедитесь, что для классификатора установлено значение .Development Status :: 5 - Production/Stable
Отметьте выпуск с помощью . Например:
git tag
$ git tag --sign --message="Tag 1.5.1" 1.5.1
Вы можете проверить свою работу, запустив .
git tag --verify <tag>
Продвигайте свою работу, включая тег .
git push --tags
Убедитесь, что у вас есть абсолютно чистое дерево, запустив .
git clean -dfx
Запустите, чтобы сгенерировать пакеты выпуска. Это создаст пакеты выпуска в каталоге.
make -f extras/Makefile
dist/
Сгенерируйте хэши релиз-пакетов:
$ cd dist $ md5sum * $ sha1sum * $ sha256sum *
Создайте файл «контрольных сумм»,
Django-<<VERSION>>.checksum.txt
содержащий хеши и информацию о выпуске. Начните с этого шаблона и вставьте правильную версию, дату, идентификатор ключа GPG (от ), URL-адрес выпуска и контрольные суммы:gpg --list-keys --keyid-format LONG
This file contains MD5, SHA1, and SHA256 checksums for the source-code tarball and wheel files of Django <<VERSION>>, released <<DATE>>. To use this file, you will need a working install of PGP or other compatible public-key encryption software. You will also need to have the Django release manager's public key in your keyring; this key has the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT keyserver. For example, if using the open-source GNU Privacy Guard implementation of PGP: gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX Once the key is imported, verify this file:: gpg --verify <<THIS FILENAME>> Once you have verified this file, you can use normal MD5, SHA1, or SHA256 checksumming applications to generate the checksums of the Django package and compare them to the checksums listed below. Release packages: ================= https://www.djangoproject.com/m/releases/<<RELEASE TAR.GZ FILENAME>> https://www.djangoproject.com/m/releases/<<RELEASE WHL FILENAME>> MD5 checksums: ============== <<MD5SUM>> <<RELEASE TAR.GZ FILENAME>> <<MD5SUM>> <<RELEASE WHL FILENAME>> SHA1 checksums: =============== <<SHA1SUM>> <<RELEASE TAR.GZ FILENAME>> <<SHA1SUM>> <<RELEASE WHL FILENAME>> SHA256 checksums: ================= <<SHA256SUM>> <<RELEASE TAR.GZ FILENAME>> <<SHA256SUM>> <<RELEASE WHL FILENAME>>
Подпишите файл контрольной суммы ( ). При этом создается подписанный документ, который затем можно проверить с помощью .
gpg --clearsign --digest-algo SHA256 Django-<version>.checksum.txt
Django-<version>.checksum.txt.asc
gpg --verify Django-<version>.checksum.txt.asc
Если вы выпускаете несколько выпусков, повторите эти шаги для каждого выпуска.
Сделать релиз (ы) общедоступным ¶
Теперь вы готовы опубликовать релиз. Сделать это:
Загрузите пакеты выпуска на сервер djangoproject, заменив AB на соответствующий номер версии, например 1.5 для выпуска 1.5.x:
$ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
Если это альфа-версия новой серии, вам нужно будет создать каталог AB
Загрузите файл (ы) контрольной суммы:
$ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
Проверьте правильность установки пакетов выпуска с помощью
easy_install
иpip
. Вот один из способов:$ RELEASE_VERSION='1.7.2' $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3` $ python -m venv django-easy-install $ . django-easy-install/bin/activate $ easy_install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz $ deactivate $ python -m venv django-pip $ . django-pip/bin/activate $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz $ deactivate $ python -m venv django-pip-wheel $ . django-pip-wheel/bin/activate $ python -m pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py3-none-any.whl $ deactivate
Это всего лишь проверка того, что архивы доступны (т.е. перенаправления открыты) и что они установлены правильно, но выявляются глупые ошибки.
Попросите нескольких человек в IRC проверить контрольные суммы, посетив файл контрольных сумм (например, https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt ) и следуя инструкциям в нем. Чтобы получить бонусные баллы, они также могут распаковать загруженный архив релиза и убедиться, что его содержимое является правильным (правильные номера версий, отсутствие случайных
.pyc
или других нежелательных файлов).Загрузите пакеты выпуска в PyPI (для предварительных выпусков загружайте только файл wheel):
$ twine upload -s dist/*
Перейдите на страницу добавления выпуска в админке , введите новый номер выпуска точно так, как он указан в имени архива (Django- <version> .tar.gz). Так, например, введите «1.5.1» или «1.4c2» и т. Д. Если выпуск является частью ветви LTS, отметьте это так.
Если это альфа-версия новой серии, также создайте объект Release для окончательной версии, убедившись, что поле Дата выпуска пусто, тем самым пометив его как невыпущенный . Например, при создании объекта Release для
3.1a1
, также создайте3.1
с пустым полем Release date.Сделайте сообщение в блоге о выпуске в прямом эфире.
Для выпуска новой версии (например, 1.5, 1.6) обновите стабильную версию документов по умолчанию, установив
is_default
флажокTrue
на соответствующемDocumentRelease
объекте вdocs.djangoproject.com
базе данных (это автоматически изменит его значениеFalse
для всех остальных); вы можете сделать это с помощью администратора сайта.Создайте новые
DocumentRelease
объекты для каждого языка, на котором есть запись для предыдущего выпуска. Обновите файл robots.docs.txt на djangoproject.com , скопировав записи из текущей стабильной ветки в репозитории. Например, при выпуске Django 2.2:manage_translations.py robots_txt
django-docs-translations
$ git checkout stable/2.2.x $ git pull $ python manage_translations.py robots_txt
Опубликуйте объявление о выпуске в списках рассылки django-announce , django-developers и django-users . Это должно включать ссылку на сообщение в блоге с объявлением.
Если это выпуск безопасности, отправьте отдельное письмо по адресу oss-security @ lists . openwall . com . Укажите описательную тему, например «Django», а также название проблемы из примечаний к выпуску (включая идентификатор CVE). Тело сообщения должно включать сведения об уязвимости, например текст сообщения в блоге. Включите ссылку на сообщение в блоге с объявлением.
Добавить ссылку на запись в блоге в теме
#django
канала IRC: ./msg chanserv TOPIC #django new topic goes here
Пост-релиз ¶
Ты почти сделал! Все, что осталось сделать, это:
- Снова обновите
VERSION
кортежdjango/__init__.py
, увеличивая его до следующего ожидаемого выпуска. Например, после выпуска 1.5.1 обновитесьVERSION
до .VERSION = (1, 5, 2, 'alpha', 0)
- При необходимости добавьте выпуск в список версий Trac (и сделайте его стандартным, изменив
default_version
настройку в trac.ini code.djangoproject.com , если это окончательный выпуск). Новая версия XY должна быть добавлена после альфа-версии, а версия по умолчанию должна быть обновлена после выпуска с нулевой точкой. - Если это был выпуск безопасности, обновите Archive des issues de sécurité, указав подробную информацию об устраненных проблемах.
Новые задачи стабильной ветки ¶
После создания новой стабильной ветки (часто после альфа-версии) необходимо сделать несколько вещей. Некоторые из этих задач могут не выполняться релизером.
- Создайте новый
DocumentRelease
объект вdocs.djangoproject.com
базе данных для документации новой версии и обновитеdocs/fixtures/doc_releases.json
приспособление JSON, чтобы люди, не имеющие доступа к производственной БД, могли по-прежнему запускать актуальную копию сайта документации. - Создайте примечание к выпуску для новой версии функции. Используйте заглушку из предыдущей версии выпуска функции или скопируйте содержимое из предыдущей версии функции и удалите большую часть содержимого, оставив только заголовки.
- Увеличьте количество итераций PBKDF2 по умолчанию
django.contrib.auth.hashers.PBKDF2PasswordHasher
примерно на 20% (выберите круглое число). Запустите тесты и обновите 3 неудачных хеш-теста новыми значениями. Убедитесь, что это отмечено в примечаниях к выпуску (см. Пример примечания к выпуску 1.8). - Удалите функции, срок поддержки которых истек. Для ясности каждое удаление должно выполняться в отдельной фиксации. В сообщении о фиксации добавьте «refs #XXXX» к исходной заявке, с которой началось прекращение поддержки, если это возможно.
- Удалите , и
аннотации в документации из двух выпусков назад. Например, в Django 1.9 примечания к 1.7 будут удалены.
.. versionadded::
.. versionadded::
.. deprecated::
- Добавьте новую ветку для чтения документов . Поскольку автоматически сгенерированные имена версий («stable-ABx») отличаются от имен версий, используемых в «Прочтите документацию» («ABx»), создайте билет, запрашивающий новую версию.
Примечания по настройке кортежа VERSION ¶
Версия Django контролируется кортежем VERSION
в django/__init__.py
. Это пятиэлементный кортеж, содержащий:
- Основная версия.
- Дополнительная версия.
- Микроверсия.
- Статус, который может быть «альфа», «бета», «rc» или «окончательный».
- Серийный номер в случае следующих выпусков альфа / бета / RC (например, «бета 1», «бета 2» и т. Д.).
Для окончательного выпуска статус всегда «final» и серийный номер 0. Серийный номер 0 со статусом «alpha» сообщается как «pre-alpha».
Некоторые примеры :
(1, 2, 1, 'final', 0)
→ «1.2.1»(1, 3, 0, 'alpha', 0)
→ «1.3 пре-альфа»(1, 3, 0, 'beta', 2)
→ «1.3 бета 2»