Как формируется 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. Если это альфа-версия новой серии, создайте новую стабильную ветку из main. Например, при выпуске Django 3.1:

    $ git checkout -b stable/3.1.x origin/main
    $ git push origin -u stable/3.1.x:stable/3.1.x
    

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

  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/Makefiledist/

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

    $ cd dist
    $ md5sum *
    $ sha1sum *
    $ sha256sum *
    
  12. Создайте файл «контрольных сумм», Django-<<VERSION>>.checksum.txtсодержащий хеши и информацию о выпуске. Начните с этого шаблона и вставьте правильную версию, дату, идентификатор ключа GPG (от ), имя пользователя GitHub менеджера выпуска, 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
    
    or via the GitHub API:
    
        curl https://github.com/<<RELEASE MANAGER GITHUB USERNAME>>.gpg | gpg --import -
    
    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.txtDjango-<version>.checksum.txt.ascgpg --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_txtdjango-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. Если это был выпуск безопасности, обновите Архив проблем безопасности, указав подробную информацию об устраненных проблемах.

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

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

  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»), создайте тикет с запросом новой версии.
  7. Запросите новый классификатор на PyPI . Например .Framework :: Django :: 3.1

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

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

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

Для окончательного выпуска статус всегда «окончательный», а номер серии всегда 0. Серийный номер 0 со статусом «альфа» будет сообщаться как «пре-альфа».

Несколько примеров:

  • (1, 2, 1, 'final', 0) → «1.2.1»
  • (1, 3, 0, 'alpha', 0) → «1.3 пре-альфа»
  • (1, 3, 0, 'beta', 2) → «1.3 beta 2»

Copyright ©2021 All rights reserved