Выпуск версии

Компиляторы

На каждой платформе используется та же версия gcc, что и при сборке самого Python. В настоящее время это означает:

• Сборки OS X на travis в настоящее время используют clang. Похоже, что двоичные wheel для OSX >= 10.6 можно безопасно собрать с помощью виртуальных машин travis-ci OSX 10.9 при сборке по отношению к Python из установщиков с сайта python.org;
• Сборки Windows используют инструментарий mingw-w64;
• Wheel manylinux2014 используют gcc, предоставленный в образах контейнеров Manylinux.

Для сборки двоичных файлов вам потребуется Cython. Cython компилирует файлы .pyx в дистрибутиве NumPy в файлы .c.

OpenBLAS

Все wheel ссылаются на версию OpenBLAS, предоставленную через репозиторий openblas-libs. Объектный файл (или DLL) поставляется вместе с wheel, переименованный для предотвращения конфликтов имен с другими объектами OpenBLAS, которые могут существовать в файловой системе.

Сборка исходных архивов и wheel

NumPy wheel и sdist в настоящее время собираются с помощью cibuildwheel с помощью github actions.

Сборка документации

Мы больше не собираем файлы PDF. Все, что потребуется, это

• virtualenv (pip).

Другие требования будут заполнены автоматически во время процесса сборки документации.

Загрузка на PyPI

Единственное необходимое приложение для загрузки —

• twine (pip).

Вам также понадобится токен PyPI, который лучше всего хранить в хранилище ключей. См. документацию twine хранилища ключей для получения информации о том, как это сделать.

Генерация списков авторов/запросов на вытягивание

Вам понадобится токен доступа к личному профилю https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/, чтобы скрипты могли получить доступ к репозиторию NumPy на GitHub.

• gitpython (pip)
• pygithub (pip)

Согласование графика выпуска

Типичный график выпуска включает одну бета-версию, две релиз-кандидаты и окончательный релиз. Лучше всего сначала обсудить сроки на списке рассылки, чтобы люди успели внести свои правки вовремя, слить правки в документацию вики и т. д. После того, как дата будет установлена, создайте новую ветвь maintenance/x.y.z, добавьте новые пустые примечания к выпуску для следующей версии в основной ветке и обновите этапы Trac.

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

CI собирает wheel, когда заголовок PR начинается с REL. Ваш последний PR перед выпуском должен быть отмечен таким образом, и все тесты должны пройти. Вы также можете сделать:

git clean -fxdq
python setup.py bdist_wheel
python setup.py sdist

Для получения подробностей о самом процессе сборки лучше всего прочитать пошаговые инструкции ниже.

Проверка устаревших функций

Перед созданием ветки выпуска создание ветки выпуска нужно проверить, удалён ли весь устаревший код, который должен быть удалён, и все новые устаревшие функции указывают в строке документации или предупреждении об устаревании, какую версию кода они будут удалены.

Проверка номера версии C API

Номер версии C API необходимо отслеживать в трех местах:

• numpy/_core/meson.build
• numpy/_core/code_generators/cversions.txt
• numpy/_core/include/numpy/numpyconfig.h

Процесс состоит из трех шагов.

1. Если API изменился, увеличьте C_API_VERSION в numpy/core/meson.build. API не изменяется только в том случае, если любой код, скомпилированный с использованием текущего API, будет обратной совместимостью с последней выпущенной версией NumPy. Любые изменения в C-структурах или добавления в общедоступный интерфейс сделают новый API необратно совместимым.

2. Если C_API_VERSION на первом шаге изменился или хеш API изменился, необходимо обновить файл cversions.txt. Чтобы проверить хеш, запустите скрипт numpy/_core/cversions.py и обратите внимание на хеш API, который выводится. Если этот хеш не соответствует последнему хешу в numpy/_core/code_generators/cversions.txt, хеш изменился. Используя правильную версию C_API_VERSION и хеш, добавьте новую запись в cversions.txt. Если версия API не была изменена, но хеш отличается, вам необходимо закомментировать предыдущую запись для этой версии API. Например, в NumPy 1.9 были добавлены аннотации, что изменило хеш, но API был таким же, как в 1.8. Хеш служит проверкой изменений API, но не является окончательным.

   Если шаги 1 и 2 выполнены правильно, сборка выпуска не должна выдавать предупреждение «Обнаружен несовпадающий API в начале сборки».

3. В numpy/_core/include/numpy/numpyconfig.h потребуется новая макрос NPY_X_Y_API_VERSION, где X и Y — номера основных и второстепенных версий выпуска. Значение этой макросы нужно увеличивать только с предыдущей версии, если некоторые функции или макросы в файлах include были устаревшими.

Номер версии C ABI в numpy/_core/meson.build следует обновлять только для выпуска новой версии.

Проверка примечаний к выпуску

Используйте towncrier для создания примечаний к выпуску и зафиксировать изменения. Это удалит все фрагменты из doc/release/upcoming_changes и добавит doc/release/<version>-note.rst:

towncrier build --version "<version>"
git commit -m"Create release note"

Проверьте, актуальны ли примечания к выпуску.

Обновите примечания к выпуску с разделом «Основные моменты». Упомяните некоторые из следующих пунктов:

• Основные новые функции
• Устаревшие и удаленные функции
• Поддерживаемые версии Python
• Для SciPy, поддерживаемые версии NumPy
• Перспективы на ближайшее будущее

Добавление/удаление версий Python

При добавлении или удалении версий Python необходимо отредактировать три файла:

• .github/workflows/wheels.yml # для github cibuildwheel
• .travis.yml # для cibuildwheel сборки aarch64
• setup.py # для классификатора и проверки минимальной версии.

Внесите эти изменения в обычном запросе на добавление изменений (PR) в основной репозиторий, а при необходимости — перенесите изменения на ветку. Использование префикса BLD: (метка сборки) в описании коммита запустит сборку пакетов, чтобы проверить изменения. В настоящее время пакеты для новых версий Python выпускаются после первого релиза Python rc, когда поддерживаются manylinux и cibuildwheel. Для Python 3.11 выпуск был возможен в течение недели после объявления rc1.

Перенос запросов на добавление изменений (pull requests)

Изменения, помеченные для этого выпуска, должны быть перенесены на ветку maintenance/1.21.x.

Генерация списка изменений (changelog)

Список изменений генерируется с помощью инструмента changelog:

$ spin changelog $GITHUB v1.20.0..maintenance/1.21.x > doc/changelog/1.21.0-changelog.rst

где GITHUB содержит ваш GitHub токен доступа. Текст необходимо проверить на наличие нестандартных имён авторов и удалить записи dependabot. Также рекомендуется удалить любые ссылки, которые могут присутствовать в заголовках PR, так как они плохо отображаются в формате markdown; замените их на текст в формате моноширины. Нестандартные имена авторов следует исправить, обновив файл .mailmap, что является трудоёмкой задачей. Лучше выполнить несколько тестовых запусков, прежде чем приступать к этому, и обратиться к нарушителям с помощью проблемы GitHub, чтобы получить необходимую информацию.

Завершение заметок к выпуску

Если в doc/release/upcoming_changes/ есть фрагменты заметок к выпуску, выполните spin docs, чтобы создать документацию, включите содержимое сгенерированного файла doc/source/release/notes-towncrier.rst в файл заметок к выпуску (например, doc/source/release/2.3.4-notes.rst) и удалите обработанные фрагменты в doc/release/upcoming_changes/. Это безопасно делать несколько раз в течение цикла выпуска.

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

Установить версию выпуска

Проверьте файлы pyproject.toml и pyproject.toml.setuppy и установите версию выпуска, если необходимо:

$ gvim pyproject.toml pyproject.toml.setuppy

Проверка файлов pavement.py и doc/source/release.rst

Проверьте, что файл pavement.py указывает на правильные заметки к выпуску. Он должен быть обновлён после последнего выпуска, но если нет, исправьте его сейчас. Также убедитесь, что заметки имеют запись в файле release.rst:

$ gvim pavement.py doc/source/release.rst

1. Подготовка коммита выпуска

Переключитесь на ветку для выпуска, убедитесь, что она обновлена, и очистите репозиторий:

$ git checkout maintenance/1.21.x
$ git pull upstream maintenance/1.21.x
$ git submodule update
$ git clean -xdfq

Проверка целостности:

$ python3 -m spin test -m full

Пометьте выпуск тегом и отправьте тег. Для этого требуется право записи в репозитории numpy:

$ git tag -a -s v1.21.0 -m"NumPy 1.21.0 release"
$ git push upstream v1.21.0

Если необходимо удалить тег из-за ошибки:

$ git tag -d v1.21.0
$ git push --delete upstream v1.21.0

2. Сборка колес

Пометка сборки в начале этого процесса запустит сборку колес через cibuildwheel и загрузит колеса и sdist в репозиторий подготовки. Запуск CI на github actions (для всех колес x86 и macOS arm64) занимает около 1 часа 15 минут. Запуск CI на cirrus (для aarch64 и M1) занимает меньше времени. Вы можете проверить загруженные файлы в репозитории подготовки, но имейте в виду, что он не синхронизируется с результатами выполняемых задач.

Если вы хотите вручную запустить сборку колес, вы можете сделать это:

• На github actions -> Сборщик колес есть кнопка «Запустить рабочий процесс», нажмите на нее и выберите тег для сборки
• На Cirrus в настоящее время нет простого способа вручную запускать сборку и загрузку.

Если сборка колес завершается неудачно по независящим причинам, вы можете запустить ее заново индивидуально:

• На github actions выберите Сборщик колес, нажмите на коммит, содержащий сборку, которую вы хотите запустить повторно. Слева есть список сборок колес, выберите нужную и на получившейся странице нажмите кнопку с против часовой стрелки.
• На cirrus мы пока не разработали способ.

3. Загрузка колес

После успешной сборки и подготовки всех колес загрузите их из каталога подготовки Anaconda с помощью скрипта tools/download-wheels.py.

$ cd ../numpy
$ mkdir -p release/installers
$ python3 tools/download-wheels.py 1.21.0

4. Генерация файлов README

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

$ paver write_release

5. Загрузка на PyPI

Загрузка на PyPI с помощью twine. Требуется недавняя версия twine после недавних изменений в PyPI, здесь использовалась версия 3.4.1.

$ cd ../numpy
$ twine upload release/installers/*.whl
$ twine upload release/installers/numpy-1.21.0.tar.gz  # Upload last.

Если одна из команд прервется, вам, возможно, придется выборочно загрузить оставшиеся файлы, так как PyPI не позволяет загружать один и тот же файл дважды. Файл исходного кода следует загружать последним, чтобы избежать проблем с синхронизацией, которые могут возникнуть, если пользователи pip получат доступ к файлам во время этого процесса, что заставит pip строить из исходного кода вместо загрузки двоичного колеса. PyPI позволяет только одно распределение исходного кода, здесь мы выбрали архив zip.

6. Загрузка файлов на GitHub

Перейдите на numpy/numpy, там должен быть v1.21.0 tag, нажмите кнопку редактирования для этого тега. Есть два способа добавления файлов: использование окна редактирования текста и загрузка двоичных файлов. Начните с редактирования release/README.md, который преобразуется из версии rst с использованием pandoc. Необходимо исправить: строки PR из изменения, если они включены, они обрезаны и требуют восстановления; ссылки должны быть изменены на моноширинный текст. Затем скопируйте содержимое в буфер обмена и вставьте его в окно текста. Возможно, потребуется несколько попыток, чтобы добиться правильного вида. Затем

• Загрузите release/installers/numpy-1.21.0.tar.gz как двоичный файл.
• Загрузите release/README.rst как двоичный файл.
• Загрузите doc/changelog/1.21.0-changelog.rst как двоичный файл.
• Отметьте флажок предварительного релиза, если это предварительный релиз.
• Нажмите кнопку {Publish,Update} release внизу.

7. Загрузка документов на numpy.org (пропустить для предварительных релизов)

Этот шаг необходим только для финальных релизов и может быть пропущен для предварительных релизов и большинства исправлений. make merge-doc клонирует репозиторий numpy/doc в doc/build/merge и обновляет его с новой документацией:

$ git clean -xdfq
$ git co v1.21.0
$ rm -rf doc/build  # want version to be current
$ python -m spin docs merge-doc --build
$ pushd doc/build/merge

Если серия релизов новая, вам нужно добавить новый раздел на главную страницу doc/build/merge/index.html сразу после комментария «вставьте сюда»:

$ gvim index.html +/'insert here'

Кроме того, обновите файл json смены версий, чтобы добавить новый выпуск и обновить отмеченную версию (stable):

$ gvim _static/versions.json

В противном случае необходимо обновить только ссылку zip с новым именем тега. Поскольку мы больше не генерируем файлы pdf удалите строку для файлов pdf если она присутствует:

$ gvim index.html +/'tag v1.21'

Вы можете выполнить «тестовый запуск» новой документации в браузере, чтобы убедиться в работоспособности ссылок:

$ firefox index.html  # or google-chrome, etc.

Обновите стабильную ссылку и обновите:

$ ln -sfn 1.21 stable
$ ls -l  # check the link

После того, как все покажется удовлетворительным, обновите, зафиксируйте и отправьте изменения:

$ python3 update.py
$ git commit -a -m"Add documentation for v1.21.0"
$ git push
$ popd

8. Сброс ветки поддержки в состояние разработки (пропустить для предварительных релизов)

Создайте заметки о выпуске для следующего релиза и отредактируйте их, чтобы установить версию. Эти заметки будут скелетными и содержать мало контента:

$ cp doc/source/release/template.rst doc/source/release/1.21.1-notes.rst
$ gvim doc/source/release/1.21.1-notes.rst
$ git add doc/source/release/1.21.1-notes.rst

Добавьте новые заметки о выпуске в список выпусков документации и обновите переменную RELEASE_NOTES в pavement.py:

$ gvim doc/source/release.rst pavement.py

Обновите version в pyproject.toml и pyproject.toml.setuppy:

$ gvim pyproject.toml pyproject.toml.setuppy

Зафиксируйте результат:

$ git commit -a -m"MAINT: prepare 1.21.x for further development"
$ git push origin HEAD

Перейдите на GitHub и создайте запрос на изменение.

9. Объявление о выпуске на numpy.org (пропустить для предварительных релизов)

Предполагается, что вы создали форк numpy/numpy.org:

$ cd ../numpy.org
$ git checkout main
$ git pull upstream main
$ git checkout -b announce-numpy-1.21.0
$ gvim content/en/news.md

• Для всех выпусков перейдите к нижней части страницы и добавьте ссылку в одну строку. Обратитесь к предыдущим ссылкам для примера.
• Для выпуска *.0 в цикле добавьте новый раздел в верхней части со кратким описанием новых функций и укажите новостную ссылку на него.

зафиксируйте и отправьте:

$ git commit -a -m"announce the NumPy 1.21.0 release"
$ git push origin HEAD

Перейдите на GitHub и создайте запрос на изменение.

10. Объявление на списках рассылки

Выпуск должен быть объявлен на списках рассылки numpy-discussion, scipy-devel и python-announce-list. Обратитесь к предыдущим объявлениям для шаблона. Список авторов и список запросов на изменения аналогичны тем, что генерируются для заметок о выпуске выше. Если вы пересылаете, убедитесь, что python-announce-list находится в BCC, чтобы ответы не отправлялись на этот список.

11. Обновление основного модуля после выпуска (пропустить для предварительных релизов)

Переключитесь на основную ветку и переместите изменения в документацию:

$ git checkout -b post-1.21.0-release-update
$ git checkout maintenance/1.21.x doc/source/release/1.21.0-notes.rst
$ git checkout maintenance/1.21.x doc/changelog/1.21.0-changelog.rst
$ git checkout maintenance/1.21.x .mailmap  # only if updated for release.
$ gvim doc/source/release.rst  # Add link to new notes
$ git status  # check status before commit
$ git commit -a -m"MAINT: Update main after 1.21.0 release."
$ git push origin HEAD

Перейдите на GitHub и создайте запрос на изменение.

12. Обновление oldest-supported-numpy

Если этот выпуск — первый, поддерживающий новую версию Python, или первый, предоставляющий колеса для новой платформы или версии PyPy, необходимо обновить привязки версий в scipy/oldest-supported-numpy. Либо отправьте PR с изменениями в setup.cfg, либо откройте вопрос с информацией об необходимых изменениях.

Создание ветки

Это необходимо только при создании новой ветки поддержки. Поскольку NumPy теперь зависит от тегов для определения версии, начало нового цикла разработки в основной ветке требует аннотированного тега. Это делается следующим образом:

$ git checkout main
$ git pull upstream main
$ git commit --allow-empty -m'REL: Begin NumPy 1.22.0 development'
$ git push upstream HEAD

Если отправка завершилась неудачно из-за слияния новых запросов на изменение, сделайте:

$ git pull --rebase upstream

и повторите отправку. После успешной отправки пометьте ее:

$ git tag -a -s v1.22.0.dev0 -m'Begin NumPy 1.22.0 development'
$ git push upstream v1.22.0.dev0

затем создайте новую ветку и отправьте ее:

$ git branch maintenance/1.21.x HEAD^
$ git push upstream maintenance/1.21.x

Подготовка основной ветки для дальнейшей разработки

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

$ git checkout -b 'prepare-main-for-1.22.0-development' v1.22.0.dev0

Удалите фрагменты заметок о выпуске:

$ git rm doc/release/upcoming_changes/[0-9]*.*.rst

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

$ cp doc/source/release/template.rst doc/source/release/1.22.0-notes.rst
$ gvim doc/source/release/1.22.0-notes.rst  # put the correct version
$ git add doc/source/release/1.22.0-notes.rst
$ gvim doc/source/release.rst  # add new notes to notes index
$ git add doc/source/release.rst

Обновите pavement.py и обновите переменную RELEASE_NOTES для указания на новые заметки:

$ gvim pavement.py
$ git add pavement.py

Обновите cversions.txt, чтобы добавить текущий выпуск. На этом раннем этапе не должно быть нового хеша, о котором следует беспокоиться, просто добавьте комментарий, следуя предыдущей практике:

$ gvim numpy/_core/code_generators/cversions.txt
$ git add numpy/_core/code_generators/cversions.txt

Проверьте свою работу, зафиксируйте ее и отправьте:

$ git status  # check work
$ git commit -m'REL: Prepare main for NumPy 1.22.0 development'
$ git push origin HEAD

Теперь создайте запрос на изменение.