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

Следующие руководства включают подробную информацию о том, как подготовить выпуск NumPy.

Как подготовить выпуск#

Эти инструкции дают обзор того, что необходимо для сборки бинарных релизов NumPy.

numpy.polynomial.chebyshev.chebcompanion#

Полезную информацию можно найти в сборка-из-исходников в документации, а также в этих трех файлах:

Поддерживаемые платформы и версии#

NEP 29 описывает, какие версии Python поддерживаются как минимум. Обычно мы решаем поддерживать данную версию Python немного дольше этого минимума, чтобы избежать проблем у других проектов - это на усмотрение менеджера выпуска.

  • macOS

    Мы стремимся поддерживать тот же набор версий macOS, которые поддерживаются Python.org и cibuildwheel для любой данной версии Python. Мы создаём бинарные колеса для macOS, совместимые с распространёнными методами установки Python, например, с python.org, python-build-standalone (те самые uv установки), системный Python, conda-forge, Homebrew и MacPorts.

  • Windows

    Мы собираем 32- и 64-битные колеса для Windows. Поддерживаются Windows 7, 8 и 10. Мы собираем NumPy с использованием наиболее удобных компиляторов, которые (по состоянию на август 2025) MSVC для x86/x86-64 и Clang-cl для arm64, cibuildwheel и GitHub Actions.

  • Linux

    Мы собираем и поставляем manylinux и musllinux колеса для платформ x86-64 и aarch64 на PyPI. Колеса для 32-битных платформ в настоящее время не предоставляются. Мы стремимся поддерживать самые старые не-EOL версии и обновлять примерно в соответствии с cibuildwheel. См. pypa/manylinux и эта таблица совместимости дистрибутивов для получения дополнительной информации.

  • BSD / Solaris / AIX

    Двоичные сборки (wheels) не предоставляются на PyPI, однако мы ожидаем, что сборка из исходного кода на этих платформах будет работать нормально.

Цепочки инструментов#

Для сборки колес мы используем следующие инструментальные цепочки:

  • Linux: мы используем компиляторы по умолчанию в manylinux/musllinux Образы Docker, которые обычно представляют собой относительно свежую версию GCC.

  • macOS: мы используем компиляторы Apple Clang и версию XCode, установленные на образе GitHub Actions runner.

  • Windows: для x86 и x86-64 мы используем цепочку инструментов MSVC и Visual Studio по умолчанию, установленную на соответствующем образе GitHub Actions runner. Обратите внимание, что в прошлом иногда было необходимо использовать более старую цепочку инструментов, чтобы избежать проблем через статическую libnpymath библиотека для SciPy - пожалуйста проверьте numpy/numpy-release код и логи CI на случай, если потребуется определить точные номера версий.

Для сборки из исходного кода минимальные версии компиляторов отслеживаются в корневом meson.build файл.

OpenBLAS#

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

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

Мы больше не собираем pdf файлы. Требования для сборки html документация ничем не отличается от обычной разработки. См. README numpy/doc репозиторий и пошаговые инструкции в doc/RELEASE_WALKTHROUGH.rst для получения дополнительной информации.

Загрузка в PyPI#

Создание релиза на PyPI и загрузка колес и sdist автоматизированы в CI и используют Доверенная публикация PyPI. См. README в numpy/numpy-release репозиторием и пошаговыми инструкциями в doc/RELEASE_WALKTHROUGH.rst для получения дополнительной информации.

Генерация списков авторов/PR#

Вам потребуется персональный токен доступа https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ чтобы скрипты могли получить доступ к репозиторию NumPy на GitHub. С этим токеном содержимое журнала изменений автора/PR можно сгенерировать, запустив spin changelogДля этого может потребоваться несколько дополнительных пакетов, таких как gitpython и pygithub.

Что выпускается#

На PyPI мы выпускаем wheels для ряда платформ (как обсуждалось выше) и sdist.

На GitHub Releases мы публикуем тот же sdist (потому что исходные архивы, автоматически создаваемые GitHub, неполные), а также заметки о выпуске и журнал изменений.

Процесс выпуска#

Согласовать график выпуска#

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

Проверить устаревшие функции#

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

Проверить номер версии 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 — основные и второстепенные номера версии выпуска. Значение, присвоенное этому макросу, нужно увеличивать только по сравнению с предыдущей версией, если некоторые функции или макросы в файлах заголовков были устаревшими.

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

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

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

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

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

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

  • основные новые функции

  • устаревшие и удалённые функции

  • поддерживаемые версии Python

  • для SciPy, поддерживаемая версия NumPy

  • перспективы на ближайшее будущее

Пошаговые инструкции#

Это пошаговое руководство по релизу NumPy 2.4.0 на Linux, который будет первым функциональным релизом, использующим numpy/numpy-release репозиторий.

Команды можно скопировать в командную строку, но обязательно замените 2.4.0 на правильную версию. Это следует читать вместе с руководство по общему выпуску.

Подготовка объекта#

Перед началом создания релиза используйте requirements/*_requirements.txt файлы, чтобы убедиться, что у вас есть необходимое программное обеспечение. Большинство ПО можно установить с помощью pip, но некоторое потребует apt-get, dnf или того, что использует ваша система для установки ПО. Вам также понадобится персональный токен доступа GitHub (PAT) для отправки документации. Есть несколько способов упростить процесс:

  • Git можно настроить на использование хранилища ключей для хранения вашего персонального токена доступа GitHub. Ищите подробности в интернете.

  • Вы можете использовать keyring приложение для хранения пароля PyPI для twine. См. онлайн-документацию twine для подробностей.

До выпуска#

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

При добавлении или удалении версий Python необходимо отредактировать несколько конфигурационных и CI-файлов, помимо изменения минимальной версии в pyproject.tomlВнесите эти изменения в обычный PR против основной ветки и выполните обратный порт при необходимости. В настоящее время мы выпускаем сборки для новых версий Python после первого релиз-кандидата Python, как только manylinux и cibuildwheel поддерживают эту новую верси Python.

Запросы на перенос изменений#

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

Обновить вехи 2.4.0#

Посмотрите на issues/prs с вехами 2.4.0 и либо отложите их на более позднюю версию, либо, возможно, удалите веху. Возможно, потребуется добавить веху.

Проверьте репозиторий numpy-release#

Вещи, которые нужно проверить, это cibuildwheel версия в .github/workflows/wheels.yml и openblas версии в openblas_requirements.txt.

Создайте PR для выпуска#

Обычно для PR выпуска необходимо обновить или создать четыре документа:

  • Журнал изменений

  • Примечания к выпуску

  • The .mailmap файл

  • The pyproject.toml файл

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

REL: Prepare for the NumPy 2.4.0 release

- Create 2.4.0-changelog.rst.
- Update 2.4.0-notes.rst.
- Update .mailmap.
- Update pyproject.toml

Установить версию релиза#

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

$ gvim pyproject.toml

Проверьте doc/source/release.rst файл#

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

$ gvim doc/source/release.rst

Создать журнал изменений#

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

$ spin changelog $GITHUB v2.3.0..maintenance/2.4.x > doc/changelog/2.4.0-changelog.rst

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

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

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

$ spin notes
$ gvim doc/source/release/notes-towncrier.rst doc/source/release/2.4.0-notes.rst

Как только notes-towncrier содержимое было включено в примечания к выпуску .. include:: notes-towncrier.rst директива может быть удалена. Заметки всегда потребуют некоторых исправлений, введение нужно будет написать, и значительные изменения должны быть выделены. Для патч-релизов текст журнала изменений также может быть добавлен, но не для первоначального релиза, так как он слишком длинный. Проверьте предыдущие заметки о выпуске, чтобы увидеть, как это делается.

Протестировать сборки колес#

После слияния PR релиза перейдите к numpy-release репозиторий в вашем браузере и вручную запустить workflow на maintenance/2.4.x ветвь с использованием Run workflow кнопка в actions. Убедитесь, что цель загрузки — none в окружение выпадающий список. Сборка колес занимает около 1 часа, но иногда GitHub работает очень медленно. Если некоторые сборки колес не удаются по несвязанным причинам, вы можете перезапустить их как обычно в интерфейсе GitHub Actions с re-run failed. После сборки колес проверьте результаты, убедившись, что количество артефактов верно, имена колес соответствуют ожиданиям и т.д. Если всё выглядит хорошо, приступайте к выпуску.

Обзор релиза#

Обратите внимание, что в приведённых ниже фрагментах кода upstream ссылается на корневой репозиторий на GitHub и origin в его форк в ваших личных репозиториях GitHub. Возможно, вам потребуется внести корректировки, если вы не форкнули репозиторий, а просто склонировали его локально. Вы также можете редактировать .git/config и добавьте upstream если он еще не присутствует.

1. Отметить коммит релиза#

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

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

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

$ python3 -m spin test -m full

Пометьте релиз и отправьте метку. Это требует права на запись в репозиторий numpy:

$ git tag -a -s v2.4.0 -m"NumPy 2.4.0 release"
$ git push upstream v2.4.0

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

$ git tag -d v2.4.0
$ git push --delete upstream v2.4.0

2. Собрать wheels и sdist#

Перейти к numpy-release репозиторий в браузере и вручную запустить рабочий процесс на maintenance/2.4.x ветка с использованием Run workflow кнопка в actions. Убедитесь, что цель загрузки - pypi в окружение выпадающий список. сборка колес занимает около 1 часа, но иногда GitHub очень медленный. Если некоторые сборки колес не удались по несвязанным причинам, вы можете перезапустить их как обычно в интерфейсе GitHub Actions с re-run failed. После сборки колес проверьте результаты, убедившись, что количество артефактов верное, имена колес соответствуют ожиданиям и т.д. Если всё выглядит хорошо, запустите загрузку.

3. Загрузите файлы в GitHub Releases#

Перейти к numpy/numpy, должен быть v2.4.0 тег, нажмите на него и нажмите кнопку редактирования для этого тега и обновите заголовок на "v2.4.0 (<дата>)". Есть два способа добавления файлов: с использованием редактируемого текстового окна и в виде двоичных загрузок. Текстовое окно требует markdown, поэтому переведите заметки о выпуске из rst в md:

$ python tools/write_release.py 2.4.0

это создаст release/README.md файл, который можно редактировать. Проверьте результат, чтобы убедиться, что он выглядит правильно. Возможные исправления: перенесенные строки, которые нужно развернуть, и ссылки, которые следует изменить на моноширинный текст. Затем скопируйте содержимое в буфер обмена и вставьте его в текстовое окно. Может потребоваться несколько попыток, чтобы добиться правильного вида. Затем

  • Скачать sdist (numpy-2.4.0.tar.gz) из PyPI и загрузить его на GitHub как бинарный файл. Вы не можете сделать это с помощью pip.

  • Загрузить release/README.rst как двоичный файл.

  • Загрузить doc/changelog/2.4.0-changelog.rst как двоичный файл.

  • Установите флаг предварительного выпуска, если это предварительный выпуск.

  • Нажмите Publish release кнопка внизу.

Примечание

Пожалуйста, убедитесь, что все 3 файла загружены и присутствуют, а текст релиза завершен. Релизы настроены как неизменяемые, поэтому ошибки нельзя (легко) исправить.

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

Примечание

Вам понадобится персональный токен доступа GitHub для отправки обновления.

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

$ git clean -xdfq
$ git co v2.4.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) и preferred:

$ gvim _static/versions.json

Затем запустите update.py для обновления версии в _static:

$ python3 update.py

Вы можете "протестировать" новую документацию в браузере, чтобы убедиться, что ссылки работают, хотя выпадающий список версий не изменится, он получает информацию из numpy.org:

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

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

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

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

$ git commit -a -m"Add documentation for v2.4.0"
$ git push git@github.com:numpy/doc
$ popd

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

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

$ git checkout -b begin-2.4.1 maintenance/2.4.x
$ cp doc/source/release/template.rst doc/source/release/2.4.1-notes.rst
$ gvim doc/source/release/2.4.1-notes.rst
$ git add doc/source/release/2.4.1-notes.rst

Добавьте ссылку на новые примечания к релизу:

$ gvim doc/source/release.rst

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

$ gvim pyproject.toml

Зафиксируйте результат, отредактируйте сообщение коммита, отметьте файлы в коммите и добавьте строку [skip cirrus] [skip actions], затем нажмите:

$ git commit -a -m"MAINT: Prepare 2.4.x for further development"
$ git rebase -i HEAD^
$ git push origin HEAD

Перейдите на GitHub и создайте PR. Он должен быть быстро объединён.

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

Это предполагает, что вы форкнули numpy/numpy.org:

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

  • Для всех релизов перейдите вниз страницы и добавьте ссылку в одну строку. Посмотрите на предыдущие ссылки для примера.

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

  • Отредактируйте поля newsHeader и date в верхней части news.md

  • Также отредактируйте buttonText в строке 14 в content/en/config.yaml

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

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

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

7. Объявить в списках рассылки#

Релиз должен быть объявлен в списках рассылки numpy-discussion и python-announce-list. Посмотрите предыдущие объявления для базового шаблона. Списки участников и PR такие же, как сгенерированные для примечаний к выпуску выше. Если вы пересылаете сообщение, убедитесь, что python-announce-list указан в скрытой копии (BCC), чтобы ответы не отправлялись в этот список.

8. Обновление основной ветки после выпуска (пропустить для предварительных выпусков)#

Переключитесь на основную ветку и перенесите изменения документации вперёд. Вы также можете обновить эти заметки, если процедуры изменились или улучшились:

$ git checkout -b post-2.4.0-release-update main
$ git checkout maintenance/2.4.x doc/source/release/2.4.0-notes.rst
$ git checkout maintenance/2.4.x doc/changelog/2.4.0-changelog.rst
$ git checkout maintenance/2.4.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 2.4.0 release."
$ git push origin HEAD

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

Пошаговое руководство по ветке#

Это руководство содержит пошаговое описание ветвления NumPy 2.3.x в Linux. Команды можно скопировать в командную строку, но обязательно замените 2.3 и 2.4 на правильные версии. Рекомендуется сделать .mailmap как можно более актуальным перед созданием ветки, что может занять несколько недель.

Это следует читать вместе с руководство по общему выпуску.

Ветвление#

Создайте ветку#

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

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

Если push не удался из-за слияния новых PR, сделайте:

$ git pull --rebase upstream

и повторите push. Как только push завершится успешно, добавьте тег:

$ git tag -a -s v2.4.0.dev0 -m'Begin NumPy 2.4.0 development'
$ git push upstream v2.4.0.dev0

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

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

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

Создайте ветку PR для подготовки main для дальнейшей разработки:

$ git checkout -b 'prepare-main-for-2.4.0-development' v2.4.0.dev0

Удалить фрагменты примечаний к выпуску:

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

Создать каркас новых заметок о выпуске и добавить в индекс:

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

Обновить 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 2.4.0 development'
$ git push origin HEAD

Теперь создайте pull request.

На этой странице