Как устроен Django?

В этом документе объясняется, как создается релиз Django.

Пожалуйста, обновляйте эти инструкции, если вы вносите какие-либо изменения! Главное здесь - быть описательным, а не предписывающим, поэтому не стесняйтесь упрощать или вносить другие изменения в процедуру, но затем обновите этот документ соответствующим образом!

Предварительный просмотр

Возможно, вам потребуется создать три разных типа сообщений:

  • Публикации по безопасности: объявление и устранение уязвимости. Обычно это включает две или три одновременных публикации - например. 1.5.x, 1.6.x и, в зависимости от времени, возможно 1.7 alpha / beta / rc.
  • Нормальные выпуски версии: либо финальный выпуск (например, 1.5), либо исправляющее обновление (например, 1.5.1).
  • Препринты: напр. 1.6 альфа, бета или RC.

Краткая версия следующих шагов:

  1. Если это публикация по безопасности, предварительно уведомите список рассылки по безопасности за неделю до фактической публикации.
  2. Вычитайте примечания к выпуску, особенно в отношении их организации и формулировок. Напишите черновик сообщения в блоге и рекламное письмо.
  3. Обновите номера версий и создайте пакеты выпуска.
  4. Отправьте пакет (ы) на сервер djangoproject.com .
  5. Отправьте новые версии на сервер PyPI.
  6. Объявите новую версию в интерфейсе администрирования djangoproject.com .
  7. Опубликуйте сообщение в блоге и отправьте объявление по электронной почте.
  8. Обновите номера версий после публикации.

Подробностей много, держитесь!

Предпосылки

Перед тем, как начать, вам нужно сделать несколько вещей:

  • Ключ GPG. Если ключ, который вы хотите использовать, не является вашим ключом подписи по умолчанию, вам нужно будет добавить к каждой команде подписи GPG ниже, где - адрес электронной почты, связанный с ключом, который вы собираетесь использовать.-u [email protected] [email protected]

  • Установка некоторых необходимых пакетов Python

    $ python -m pip install wheel twine
    
  • Доступ к учетной записи Django на PyPI. Создайте файл с вашей аутентификационной информацией:

    ~ / .pypirc
    [pypi]
    username:YourUsername
    password:YourPassword
    
  • Доступ к серверу djangoproject.com для отправки на него файлов.

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

  • Право публикации на django-announce .

  • Если это публикация по безопасности, получите доступ к списку рассылки предварительного уведомления.

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

Предварительные задачи

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

  1. Если это выпуск безопасности, отправьте предварительное уведомление за неделю до выпуска. Шаблон для этого письма и список получателей находятся в частной django-security вики GitHub. BCC получатели предварительного уведомления. Подпишите электронное письмо ключом, который вы будете использовать для выпуска, и включите идентификаторы CVE (запрашиваемые у поставщика: djangoproject, продукт: django) и исправления для каждой исправляемой проблемы. Также уведомите django-announce о предстоящем выпуске системы безопасности.

  2. По мере приближения выпуска смотрите Trac, чтобы убедиться, что для предстоящего выпуска не осталось никаких блокировщиков выпуска.

  3. Обратитесь к другим коммиттерам, чтобы убедиться, что у них нет незафиксированных изменений для выпуска.

  4. Просмотрите примечания к выпуску, которые также включают онлайн-версию, на предмет неработающих ссылок или синтаксических ошибок reST и убедитесь, что дата примечаний к выпуску верна.

  5. Дважды проверьте, что в примечаниях к выпуску указаны сроки прекращения поддержки любых API, отмеченных как устаревшие, и что в них упоминаются любые изменения в поддержке версии Python.

  6. Еще раз проверьте, есть ли в указателе примечаний к выпуску ссылка на примечания к новому выпуску; это будет в docs/releases/index.txt .

  7. Если это функциональный выпуск, убедитесь, что переводы из Transifex были интегрированы. Обычно это делает отдельный менеджер переводов, а не релизер, но вот шаги. Если у вас есть учетная запись на Transifex:

    $ python scripts/manage_translations.py fetch
    

    а затем зафиксируйте измененные / добавленные файлы (как .po, так и .mo). Иногда возникают ошибки проверки, которые необходимо отладить, поэтому не выполняйте эту задачу непосредственно перед тем, как потребуется выпуск.

  8. Обновите страницу руководства 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
    

    а затем зафиксируйте измененную страницу руководства.

  9. Если это альфа-версия новой серии, создайте новую стабильную ветку из 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
    
  10. Если это выпуск новой серии с нулевой точкой, создайте новую ветку из текущей стабильной ветки в репозитории 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
    

Подготовка к публикации

Напишите сообщение в блоге с объявлением о публикации. Вы можете написать его на сайте администрирования, отметив его как неактивное. Вот несколько примеров: Пример объявления о выпуске системы безопасности , например, обычное публикуемое объявление , предварительная публикация образца объявления .

Собственно накатил релиз

Хорошо, это самая интересная часть, когда мы выпускаем релиз!

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

  2. Релиз всегда начинается с ветки релиза, поэтому вы должны быть уверены, что находитесь в стабильной ветке и обновлены. Например:

    $ git checkout stable/1.5.x
    $ git pull
    
  3. Если это выпуск безопасности, слейте соответствующие исправления из 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

  4. Для выпуска функции удалите заголовок вверху заметок о выпуске и добавьте дату выпуска в следующей строке. Для выпуска патча замените датой выпуска. Сделайте это изменение во всех ветках, где находятся примечания к выпуску для конкретной версии.UNDER DEVELOPMENT *Under Development*

  5. Обновите номер версии django/__init__.py для выпуска. Пожалуйста , смотрите примечания по установке VERSION кортеж ниже подробную информацию о VERSION .

  6. Если это предварительный пакет, обновите классификатор «Статус разработки», setup.cfg чтобы отразить это. В противном случае убедитесь, что для классификатора установлено значение .Development Status :: 5 - Production/Stable

  7. Отметьте выпуск с помощью . Например:git tag

    $ git tag --sign --message="Tag 1.5.1" 1.5.1
    

    Вы можете проверить свою работу, запустив .git tag --verify <tag>

  8. Продвигайте свою работу, включая тег .git push --tags

  9. Убедитесь, что у вас есть абсолютно чистое дерево, запустив .git clean -dfx

  10. Запустите, чтобы сгенерировать пакеты выпуска. Это создаст пакеты выпуска в каталоге.make -f extras/Makefile dist/

  11. Сгенерируйте хэши релиз-пакетов:

    $ cd dist
    $ md5sum *
    $ sha1sum *
    $ sha256sum *
    
  12. Создайте файл «контрольных сумм», 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>>
    
  13. Подпишите файл контрольной суммы ( ). При этом создается подписанный документ, который затем можно проверить с помощью .gpg --clearsign --digest-algo SHA256 Django-<version>.checksum.txt Django-<version>.checksum.txt.asc gpg --verify Django-<version>.checksum.txt.asc

Если вы выпускаете несколько выпусков, повторите эти шаги для каждого выпуска.

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

Теперь вы готовы опубликовать релиз. Сделать это:

  1. Загрузите пакеты выпуска на сервер djangoproject, заменив AB на соответствующий номер версии, например 1.5 для выпуска 1.5.x:

    $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B
    

    Если это альфа-версия новой серии, вам нужно будет создать каталог AB

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

    $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt
    
  3. Проверьте правильность установки пакетов выпуска с помощью 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
    

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

  4. Попросите нескольких человек в IRC проверить контрольные суммы, посетив файл контрольных сумм (например, https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt ) и следуя инструкциям в нем. Чтобы получить бонусные баллы, они также могут распаковать загруженный архив релиза и убедиться, что его содержимое является правильным (правильные номера версий, отсутствие случайных .pyc или других нежелательных файлов).

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

    $ twine upload -s dist/*
    
  6. Перейдите на страницу добавления выпуска в админке , введите новый номер выпуска точно так, как он указан в имени архива (Django- <version> .tar.gz). Так, например, введите «1.5.1» или «1.4c2» и т. Д. Если выпуск является частью ветви LTS, отметьте это так.

    Если это альфа-версия новой серии, также создайте объект Release для окончательной версии, убедившись, что поле Дата выпуска пусто, тем самым пометив его как невыпущенный . Например, при создании объекта Release для 3.1a1 , также создайте 3.1 с пустым полем Release date.

  7. Сделайте сообщение в блоге о выпуске в прямом эфире.

  8. Для выпуска новой версии (например, 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
    
  9. Опубликуйте объявление о выпуске в списках рассылки django-announce , django-developers и django-users . Это должно включать ссылку на сообщение в блоге с объявлением.

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

  11. Добавить ссылку на запись в блоге в теме #django канала IRC: ./msg chanserv TOPIC #django new topic goes here

Пост-релиз

Ты почти сделал! Все, что осталось сделать, это:

  1. Снова обновите VERSION кортеж django/__init__.py , увеличивая его до следующего ожидаемого выпуска. Например, после выпуска 1.5.1 обновитесь VERSION до .VERSION = (1, 5, 2, 'alpha', 0)
  2. При необходимости добавьте выпуск в список версий Trac (и сделайте его стандартным, изменив default_version настройку в trac.ini code.djangoproject.com , если это окончательный выпуск). Новая версия XY должна быть добавлена ​​после альфа-версии, а версия по умолчанию должна быть обновлена ​​после выпуска с нулевой точкой.
  3. Если это был выпуск безопасности, обновите Archive des issues de sécurité, указав подробную информацию об устраненных проблемах.

Новые задачи стабильной ветки

После создания новой стабильной ветки (часто после альфа-версии) необходимо сделать несколько вещей. Некоторые из этих задач могут не выполняться релизером.

  1. Создайте новый DocumentRelease объект в docs.djangoproject.com базе данных для документации новой версии и обновите docs/fixtures/doc_releases.json приспособление JSON, чтобы люди, не имеющие доступа к производственной БД, могли по-прежнему запускать актуальную копию сайта документации.
  2. Создайте примечание к выпуску для новой версии функции. Используйте заглушку из предыдущей версии выпуска функции или скопируйте содержимое из предыдущей версии функции и удалите большую часть содержимого, оставив только заголовки.
  3. Увеличьте количество итераций PBKDF2 по умолчанию django.contrib.auth.hashers.PBKDF2PasswordHasher примерно на 20% (выберите круглое число). Запустите тесты и обновите 3 неудачных хеш-теста новыми значениями. Убедитесь, что это отмечено в примечаниях к выпуску (см. Пример примечания к выпуску 1.8).
  4. Удалите функции, срок поддержки которых истек. Для ясности каждое удаление должно выполняться в отдельной фиксации. В сообщении о фиксации добавьте «refs #XXXX» к исходной заявке, с которой началось прекращение поддержки, если это возможно.
  5. Удалите , и аннотации в документации из двух выпусков назад. Например, в Django 1.9 примечания к 1.7 будут удалены... versionadded:: .. versionadded:: .. deprecated::
  6. Добавьте новую ветку для чтения документов . Поскольку автоматически сгенерированные имена версий («stable-ABx») отличаются от имен версий, используемых в «Прочтите документацию» («ABx»), создайте билет, запрашивающий новую версию.

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

Версия Django контролируется кортежем VERSION в django/__init__.py . Это пятиэлементный кортеж, содержащий:

  1. Основная версия.
  2. Дополнительная версия.
  3. Микроверсия.
  4. Статус, который может быть «альфа», «бета», «rc» или «окончательный».
  5. Серийный номер в случае следующих выпусков альфа / бета / 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»

Copyright ©2021 All rights reserved