поддержка pandas#

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

Основное руководство для участников доступно по адресу Вклад в pandas.

Роли#

pandas использует два уровня разрешений: триаж и ядро члены команды.

Участники Triage могут маркировать и закрывать проблемы и запросы на включение изменений.

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

GitHub публикует полный список разрешений.

Задачи#

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

Сортировка вновь созданных проблем (см. Триаж проблем)
Проверьте недавно открытые pull requests
Отвечать на обновления существующих проблем и запросов на слияние
Обсуждение и принятие решений по застрявшим проблемам и pull requests
Предоставить опыт / мудрость по вопросам дизайна API для обеспечения согласованности и поддерживаемости
Организация проекта (проведение / участие в собраниях разработчиков, представление pandas)

https://matthewrocklin.com/blog/2019/05/18/maintainer может быть интересным для ознакомления.

Триаж проблем#

Триаж — важный первый шаг в решении проблем, о которых сообщает сообщество, и даже частичные вклады — отличный способ помочь поддерживать pandas. Удаляйте тег «Needs Triage» только после выполнения всех шагов ниже.

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

Поблагодарить автора за создание issue

Трекер проблем — это первое взаимодействие многих людей с проектом pandas, помимо простого использования библиотеки. Поэтому мы хотим, чтобы это был приветливый и приятный опыт.
Предоставлена ли необходимая информация?

В идеале репортеры заполняют шаблон проблемы, но многие этого не делают. Если отсутствует важная информация (например, версия pandas, которую они использовали), не стесняйтесь запросить её и пометить проблему меткой «Требуется информация». Отчёт должен следовать рекомендациям в Отчеты об ошибках и запросы на улучшение. Возможно, вы захотите сослаться на это, если они не следовали шаблону.

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

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

Если новый вопрос предоставляет релевантную информацию, например, лучший или немного отличающийся пример, добавьте его к исходному вопросу в виде комментария или правки исходного сообщения.
Является ли проблема минимальной и воспроизводимой?

Для отчетов об ошибках мы просим репортера предоставить минимальный воспроизводимый пример. См. https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports для хорошего объяснения. Если пример не воспроизводится, или если это явно не минимален, не стесняйтесь спросить у репортера, может ли он предоставить пример или упростить предоставленный. Признайте, что написание минимальных воспроизводимых примеров — это тяжелая работа. Если репортер испытывает трудности, вы можете попробовать написать его самостоятельно, и мы отредактируем исходный пост, чтобы включить его.

Если воспроизводимый пример не может быть предоставлен, добавьте метку «Требуется информация».

Если предоставлен воспроизводимый пример, но вы видите упрощение, отредактируйте исходное сообщение с вашим более простым воспроизводимым примером.

Убедитесь, что проблема существует в основной ветке и что она имеет тег «Требуется сортировка» до тех пор, пока все шаги не будут выполнены. Добавьте комментарий к проблеме, как только вы подтвердите её существование в основной ветке, чтобы другие знали, что она подтверждена.
Является ли это чётко определённым запросом на функцию?

Как правило, pandas предпочитает обсуждать и проектировать новые функции в issues, прежде чем создавать pull request. Поощряйте автора включить предлагаемый API для новой функции. Попросите его написать полную docstring — это хороший способ уточнить детали.

Помечайте новые запросы на функции как "Требует обсуждения", так как нам потребуется обсуждение с несколькими сопровождающими pandas, прежде чем решить, входит ли предложение в область действия pandas.
Это вопрос по использованию?

Мы предпочитаем, чтобы вопросы по использованию задавались на StackOverflow с тегом pandas. https://stackoverflow.com/questions/tagged/pandas

Если легко ответить, не стесняйтесь ссылаться на соответствующий раздел документации, сообщите им, что в будущем такие вопросы следует задавать на StackOverflow, и закройте issue.
Какие метки и вехи мне следует добавить?

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

Если проблема четко определена и исправление кажется относительно простым, помечайте проблему как «Хорошая первая проблема».

После завершения вышеуказанного убедитесь, что удалили метку "needs triage".

Исследование регрессий#

Регрессии — это ошибки, которые непреднамеренно нарушают ранее работающий код. Обычный способ исследования регрессий — использование git bisect, который находит первый коммит, в котором была введена ошибка.

Например: пользователь сообщает, что pd.Series([1, 1]).sum() возвращает 3 в версии pandas 1.5.0 в то время как в версии 1.4.0 возвращалось 2. Для начала создайте файл t.py в вашем каталоге pandas, который содержит

import pandas as pd
assert pd.Series([1, 1]).sum() == 2

а затем запустить:

git bisect start
git bisect good v1.4.0
git bisect bad v1.5.0
git bisect run bash -c "python setup.py build_ext -j 4; python t.py"

Это находит первый коммит, изменивший поведение. C-расширения должны быть пересобраны на каждом шаге, поэтому поиск может занять некоторое время.

Выйти из bisect и пересобрать текущую версию:

git bisect reset
python setup.py build_ext -j 4

Сообщите о своих находках в соответствующем issue и упомяните автора коммита, чтобы получить их мнение.

Примечание

В bisect run в команде выше, коммиты считаются хорошими, если t.py завершается с 0 и плохим в противном случае. Когда желаемым поведением является вызов исключения, оберните код в соответствующий try/except утверждение. См. GH 35685 для больше примеров.

Закрытие вопросов#

Будьте осторожны здесь: многие люди воспринимают закрытие проблемы как то, что мы говорим, что разговор окончен. Обычно лучше дать автору отчёта некоторое время, чтобы ответить или самостоятельно закрыть свою проблему, если установлено, что поведение не является ошибкой, или функция выходит за рамки. Иногда авторы отчётов просто исчезают, и мы закроем проблему после того, как разговор угаснет. Если вы считаете, что проблему следует закрыть, но не совсем уверены, пожалуйста, примените метку "кандидат на закрытие" и подождите, пока другие сопровождающие посмотрят.

Проверка pull requests#

Любой может проверить pull request: обычные участники, триажеры или члены основной команды. Но только члены основной команды могут объединять pull request, когда они готовы.

Вот некоторые вещи, которые стоит проверить при ревью пул-реквеста.

Тесты должны находиться в логичном месте: в том же файле, что и близко связанные тесты.
Новые публичные API должны быть включены где-то в doc/source/reference/.
Новый / изменённый API должен использовать versionadded или versionchanged директив в строке документации.
Изменения, затрагивающие пользователей, должны иметь запись в соответствующем файле whatsnew.
Регрессионные тесты должны ссылаться на исходный номер issue в GitHub, например # GH-1234.
Запрос на включение изменений должен быть помечен и назначен соответствующему этапу (следующий патч-релиз для исправлений регрессий и мелких ошибок, следующий минорный этап в противном случае)
Изменения должны соответствовать нашим Политика версий.

Обратный порт#

pandas поддерживает точечные выпуски (например, 1.4.3), которые направлены на:

Исправлены ошибки в новых функциях, представленных в первом минорном релизе.

например, если новая функция была добавлена в 1.4 и содержит ошибку, исправление может быть применено в 1.4.3

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

например, если функция работала в 1.2 и перестал работать с 1.3, исправление может быть применено в 1.4.3.

Поскольку минорные выпуски pandas основаны на ветках GitHub (например, точечный релиз 1.4 основаны на 1.4.x ветка), «обратный портинг» означает слияние исправления из pull request в main ветка и соответствующая минорная ветка, связанная со следующим точечным релизом.

По умолчанию, если запрос на включение изменений назначен на следующую точечную версию в интерфейсе GitHub, процесс обратного портирования должен происходить автоматически с помощью @meeseeksdev бот после слияния pull request. Новый pull request будет создан для переноса изменений в соответствующую ветку версии. Иногда из-за конфликтов слияния потребуется ручное создание pull request для разрешения конфликта кода.

Если бот не запускает процесс обратного переноса автоматически, вы также можете написать комментарий в GitHub в объединённом запросе на включение изменений, чтобы запустить обратный перенос:

@meeseeksdev backport version-branch

Это запустит рабочий процесс, который перенесет данное изменение в ветку (например, @meeseeksdev backport 1.4.x)

Очистка старых проблем#

Каждый открытый вопрос в pandas имеет свою стоимость. Открытые вопросы усложняют поиск дубликатов и могут затруднять понимание того, что нужно сделать в pandas. Тем не менее, закрытие вопросов не является самоцелью. Наша цель — сделать pandas максимально качественным, и этого лучше всего достичь, обеспечивая высокое качество наших открытых вопросов.

Иногда ошибки исправлены, но проблема не связана в Pull Request. В таких случаях прокомментируйте, что "Это было исправлено, но нужен тест." и пометьте проблему как "Good First Issue" и "Needs Test".

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

Если в старом вопросе отсутствует воспроизводимый пример, пометьте его как «Требуется информация» и попросите предоставить его (или напишите сами, если возможно). Если он не будет предоставлен в разумные сроки, закройте его в соответствии с политиками в Закрытие вопросов.

Очистка старых pull requests#

Иногда контрибьюторы не могут завершить pull request. Если прошло некоторое время (например, две недели) с момента последнего ревью с запросом изменений, вежливо спросите, заинтересованы ли они еще в работе над этим. Если пройдет еще около двух недель без ответа, поблагодарите их за работу и затем либо:

закрыть pull request;
отправить изменения в ветку контрибьютора, чтобы завершить его работу (если вы являетесь частью pandas-core). Это может быть полезно для продвижения важного PR через финишную черту или для исправления небольшого конфликта слияния.

Если закрываете pull request, прокомментируйте исходную проблему: «Есть зависший PR #1234, который может быть полезен». Возможно, пометьте проблему как «Good first issue», если PR был близок к принятию.

Стать сопровождающим pandas#

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

Необходимые шаги для добавления сопровождающего:

Свяжитесь с участником и спросите о его интересе присоединиться.
Добавить участника в соответствующий Команда GitHub если приглашение принято.

pandas-core предназначен для членов основной команды

pandas-triage предназначено для участников triage pandas

Если добавление к pandas-core, есть два дополнительных шага:

Добавить участника в группу pandas Google.
Создать pull request, чтобы добавить GitHub-ник участника в pandas-dev/pandas/web/pandas/config.yml.

Текущий список членов основной команды находится на pandas-dev/pandas

Слияние pull-запросов#

Только члены основной команды могут объединять запросы на включение. У нас есть несколько руководств.

Обычно не следует самостоятельно сливать свои собственные pull-запросы без одобрения. Исключения включают небольшие изменения для исправления CI (например, закрепление версии пакета). Самостоятельное слияние с одобрением других членов основной команды допустимо, если вы очень уверены в изменении.
Не следует объединять запросы на включение изменений, которые имеют активное обсуждение, или запросы, у которых есть какие-либо -1 голоса от основного сопровождающего. pandas работает по консенсусу.
Для более значительных изменений желательно получить +1 как минимум от двух основных участников команды.

В дополнение к пунктам, перечисленным в Закрытие вопросов, вы должны проверить, что запрос на включение назначен на правильный этап.

Запросы на включение, объединённые с вехой патч-релиза, обычно будут перенесены нашим ботом. Убедитесь, что бот заметил слияние (он оставит комментарий в течение минуты, как правило). Если требуется ручной перенос, пожалуйста, сделайте это и удалите метку «Требуется перенос», как только вы сделали это вручную. Если вы забыли назначить веху перед тегированием, вы можете запросить у бота перенос с помощью:

@Meeseeksdev backport

Тестовая машина#

Команда в настоящее время владеет выделенным оборудованием для хостинга веб-сайта с ASV-бенчмарком производительности pandas. Результаты публикуются на https://asv-runner.github.io/asv-collection/pandas/

Конфигурация#

Машина может быть настроена с помощью Ansible плейбук в tomaugspurger/asv-runner.

Публикация#

Результаты публикуются в другом репозитории GitHub, tomaugspurger/asv-collection. Наконец, у нас есть cron-задача на нашем сервере документации для извлечения из tomaugspurger/asv-collection, чтобы обслуживать их из /speed. Спросите Тома или Йориса о доступе к веб-серверу.

Отладка#

Бенчмарки планируются с помощью Airflow. Есть панель управления для просмотра и отладки результатов. Вам потребуется настроить SSH-туннель для их просмотра

ssh -L 8080:localhost:8080 pandas@panda.likescandy.com

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

Процесс выпуска делает снимок pandas (git-коммит) доступным пользователям с определённым номером версии. После выпуска новая версия pandas будет доступна в следующих местах:

Git-репозиторий с новый тег
Исходное распределение в Релиз на GitHub
Пакеты Pip в PyPI
Пакеты Conda/Mamba в conda-forge

Процесс выпуска новой версии pandas подробно описан в следующем разделе.

Инструкции содержат который необходимо заменить на версию для выпуска (например, 1.5.2). Также ветка для выпуска , что зависит от того, является ли выпускаемая версия кандидатом на выпуск новой версии, или любой другой версией. Кандидаты на выпуск публикуются из main, в то время как другие версии выпускаются из своей ветки (например, 1.5.x).

Предварительные требования#

Для возможности выпуска новой версии pandas требуются следующие разрешения:

Объединить права с pandas и pandas-feedstock репозитории. Для последнего, откройте PR, добавив ваше имя пользователя GitHub в рецепт conda-forge.
Разрешения на отправку в main в репозитории pandas, чтобы отправить новые теги.
Права на запись в PyPI.
Доступ к нашему веб-сайту / серверу документации. Поделитесь своим открытым ключом с инфраструктурным комитетом, чтобы быть добавленным в authorized_keys файл основного пользователя сервера.
Доступ к учетным записям в социальных сетях для публикации анонсов.

Предварительный выпуск#

Согласовать с основной командой следующие темы:
- Дата выпуска (мажорные/минорные релизы обычно происходят каждые 6 месяцев, а патч-релизы ежемесячно до x.x.5, непосредственно перед следующим мажорным/минорным)
- Блокирующие проблемы (issues и PR, которые должны быть частью релиза)
- Следующая версия после выпускаемой
Обновите и очистите заметки о выпуске для версии, которая будет выпущена, включая:
- Установить конечную дату выпуска
- Удалить любой неиспользуемый пункт списка
- Убедитесь, что нет проблем с форматированием, опечаток и т.д.
Убедитесь, что CI проходит успешно для последнего коммита выпускаемой ветки.
Если это не кандидат на выпуск, убедитесь, что все запросы на перенос изменений в ветку, которая выпускается, объединены.
Создайте новый issue и milestone для версии, следующей за выпускаемой. Если выпуск был release candidate, мы обычно хотим создать issues и milestones как для следующего мажорного/минорного, так и для следующего патч-релиза. В milestone патч-релиза мы добавляем описание on-merge: backport to , поэтому помеченные PR автоматически переносятся в ветку релиза нашим ботом.
Изменить веху всех проблем и PR в выпускаемой вехе на следующую веху.

Релиз#

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

git checkout <branch>
git pull --ff-only upstream <branch>
git clean -xdf
git commit --allow-empty --author="Pandas Development Team " -m "RLS: "
git tag -a v<version> -m "Version "  # NOTE that the tag is v1.5.2 with "v" not 1.5.2
git push upstream <branch> --follow-tags

Документация для новой версии будет собрана и опубликована автоматически с помощью задания docs в CI, которое будет запущено при отправке тега.

Только если выпуск является кандидатом на выпуск, мы хотим создать новую ветку для него сразу после создания тега. Например, если мы выпускаем pandas 1.4.0rc0, мы хотели бы создать ветку 1.4.x для обратного переноса коммитов в версии 1.4. А также создать тег для обозначения начала разработки 1.5.0 (предполагая, что это следующая версия):
```
git checkout -b 1.4.x
git push upstream 1.4.x
git checkout main
git commit --allow-empty -m "Start 1.5.0"
git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0"
git push upstream main --follow-tags
```
Загрузите исходное распределение и колеса с область подготовки wheel. Будьте внимательны, чтобы убедиться, что не пропущены колеса (например, из-за неудачных сборок).

Запуск scripts/download_wheels.sh с версией, для которой вы хотите скачать wheels/sdist, должен сработать. Этот скрипт создаст dist папку внутри вашего клона pandas и поместите загруженные wheels и sdist туда:
```
scripts/download_wheels.sh <VERSION>
```
Создать новый релиз GitHub:
- Тег:
- Название: Pandas
- Описание: Скопировать описание последнего релиза того же типа (релиз-кандидат, мажорный/минорный или патч-релиз)
- Файлы: pandas-.tar.gz исходное распределение только что сгенерировано
- Установить как предрелиз: Проверять только кандидата на релиз
- Установить как последний выпуск: Оставьте отмеченным, если только не выпускаете патч для более старой версии (например, выпуск 1.4.5 после выхода версии 1.5)
Проверьте, что колеса загружаются автоматически через GitHub Actions через **Trusted Publishing** когда GitHub *Релиз* опубликовано. Не запускайте twine upload вручную.
Релиз на GitHub через несколько часов запустит автоматизированный PR conda-forge. (Если вы не хотите ждать, вы можете открыть проблему с заголовком @conda-forge-admin, please update version чтобы активировать бота.) Слейте его, когда CI станет зелёным, и он сгенерирует пакеты conda-forge.

В случае, если требуется выполнить ручной PR, версия, sha256 и поля сборки — это те, которые обычно нужно изменить. Если что-то еще в рецепте изменилось с последнего выпуска, эти изменения должны быть доступны в ci/meta.yaml.

После выпуска#

Обновите символические ссылки на стабильную документацию, войдя на наш веб-сервер и отредактировав /var/www/html/pandas-docs/stable указывать на version/ для основных и второстепенных выпусков, или version/ to version/ для патч-релизов. Точные инструкции следующие (замените примерные номера версий на соответствующие для версии, которую вы выпускаете):
- Войдите на сервер и используйте правильного пользователя.
- cd /var/www/html/pandas-docs/
- ln -sfn version/2.1 stable (для основного или промежуточного выпуска)
- ln -sfn version/2.0.3 version/2.0 (для патч-релиза)
Если выпускается основной или второстепенный релиз, откройте PR в нашем исходном коде для обновления web/pandas/versions.json, чтобы иметь нужные версии в выпадающем меню документации.
Закрыть веху и задачу для выпущенной версии.
Создать новый issue для следующего релиза с предполагаемой датой выпуска.
Откройте PR с заглушкой для заметок о выпуске следующей версии. См. например PR для версии 1.5.3. Обратите внимание, что шаблон для использования зависит от того, является ли это основным, второстепенным или патч-релизом.
Объявить о новом выпуске в официальных каналах (используйте предыдущие объявления в качестве ссылки):
- Списки рассылки pandas-dev и pydata
- Twitter, Mastodon, Telegram и LinkedIn
Обновите эти инструкции по выпуску, чтобы исправить любые ошибки и обновить информацию об изменениях с момента последнего выпуска.