Вклад в pandas#

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

Отчеты об ошибках и запросы на улучшение #

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

Проблема будет затем отображена сообществу pandas и станет открытой для комментариев/идей от других участников.

Поиск проблемы для внесения вклада #

Если вы совсем новичок в pandas или разработке с открытым исходным кодом, мы рекомендуем поискать в Вкладка "issues" на GitHub чтобы найти интересующие вас проблемы. Не назначенные проблемы с меткой Документация и хорошая первая задача обычно подходят для новых участников.

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

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

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

Отправка pull request #

Система контроля версий, Git и GitHub #

pandas размещён на GitHub, и чтобы внести вклад, вам нужно будет зарегистрироваться на бесплатный аккаунт GitHub. Мы используем Git для системы контроля версий, чтобы позволить многим людям работать над проектом вместе.

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

Документация Git.
Ресурсы Git Numpy учебное пособие.

Кроме того, проект следует workflow с форками, подробно описанному на этой странице, где участники форкают репозиторий, вносят изменения и затем создают pull request. Поэтому обязательно прочитайте и следуйте всем инструкциям в этом руководстве.

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

Ниже приведены некоторые полезные ресурсы для получения дополнительной информации о форках и pull requests на GitHub:

Начало работы с Git #

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

Создать форк pandas #

Вам понадобится ваша собственная копия pandas (т.е. форк) для работы с кодом. Перейдите на страница проекта pandas и нажмите Fork кнопку. Пожалуйста, снимите флажок, чтобы скопировать только основную ветку перед выбором Create Fork. Вам нужно будет клонировать ваш форк на свой компьютер

git clone https://github.com/your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream

Это создаёт каталог pandas-yourname и подключает ваш репозиторий к вышестоящему (основному проекту) pandas репозиторий.

Примечание

Выполнение поверхностного клонирования (с --depth==N, для некоторых N больше или равно 1) может нарушить некоторые тесты и функции, так как pd.show_versions() так как номер версии больше не может быть вычислен.

Создание ветки для новой функции #

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

git checkout main
git pull upstream main --ff-only

Затем создайте feature branch для внесения изменений. Например

git checkout -b shiny-new-feature

Это изменяет вашу рабочую ветку с main в shiny-new-feature ветка. Сохраняйте любые изменения в этой ветке специфичными для одной ошибки или функции, чтобы было ясно, что ветка привносит в pandas. Вы можете иметь много функциональных веток и переключаться между ними, используя git checkout команда.

Когда вы хотите обновить ветку feature изменениями из main после того, как вы создали ветку, проверьте раздел о обновление PR.

Внесение изменений в код #

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

Затем, после внесения изменений в код, вы можете увидеть все сделанные изменения, запустив.

git status

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

git add path/to/file-to-be-added-or-changed.py

Запуск git status снова должен отображать

On branch shiny-new-feature

     modified:   /relative/path/to/file-to-be-added-or-changed.py

Наконец, зафиксируйте изменения в локальном репозитории с пояснительным сообщением коммита

git commit -m "your commit message goes here"

Отправка ваших изменений #

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

git push origin shiny-new-feature

Здесь origin является именем по умолчанию, присвоенным вашему удалённому репозиторию на GitHub. Вы можете увидеть удалённые репозитории

git remote -v

Если вы добавили вышестоящий репозиторий, как описано выше, вы увидите что-то вроде

origin  git@github.com:yourname/pandas.git (fetch)
origin  git@github.com:yourname/pandas.git (push)
upstream        git://github.com/pandas-dev/pandas.git (fetch)
upstream        git://github.com/pandas-dev/pandas.git (push)

Теперь ваш код находится на GitHub, но он еще не является частью проекта pandas. Для этого необходимо отправить pull request на GitHub.

Создание pull request #

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

Если всё выглядит хорошо, вы готовы создать pull request. Pull request — это способ, с помощью которого код из вашего локального репозитория становится доступным сообществу GitHub для проверки и слияния в проект, чтобы появиться в следующем выпуске. Чтобы отправить pull request:

Перейдите в свой репозиторий на GitHub
Нажмите на Compare & pull request кнопка
Затем вы можете нажать на Commits и Files Changed чтобы убедиться, что всё выглядит хорошо в последний раз
Напишите описательный заголовок, включающий префиксы. pandas использует соглашение для префиксов заголовков. Вот некоторые распространённые из них вместе с общими рекомендациями по их использованию:
- ENH: Улучшение, новая функциональность
- BUG: Исправление ошибки
- DOC: Добавления/обновления документации
- TST: Добавления/обновления тестов
- BLD: Обновления процесса/скриптов сборки
- PERF: Улучшение производительности
- TYP: Аннотации типов
- CLN: Очистка кода
Напишите описание ваших изменений в Preview Discussion tab
Нажмите Send Pull Request.

Этот запрос затем отправляется сопровождающим репозитория, и они проверят код.

Обновление вашего запроса на слияние #

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

Также важно, чтобы обновления в pandas main ветки отражены в вашем pull request. Чтобы обновить вашу feature branch с изменениями в pandas main ветка, запустите:

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

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

Если есть конфликты слияния, вам нужно решить эти конфликты. Смотрите, например, https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ для объяснения, как это сделать.

После разрешения конфликтов выполните:

git add -u чтобы проиндексировать любые обновленные файлы;
git commit для завершения слияния.

Примечание

Если у вас есть незафиксированные изменения в момент, когда вы хотите обновить ветку с main, вам потребуется stash их перед обновлением (см. документация stash). Это эффективно сохранит ваши изменения, и их можно будет повторно применить после обновления.

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

git push origin shiny-new-feature

Любой git push автоматически обновит ваш pull request с изменениями из вашей ветки и перезапустит Непрерывная интеграция проверки.

Обновление среды разработки #

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

Если используется mamba, выполните:

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml --prune

Если используется pip , сделайте:

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install --upgrade -r requirements-dev.txt

Советы для успешного pull request #

Если вы дошли до Создание pull request фаза, один из основных разработчиков может взглянуть. Однако обратите внимание, что несколько человек отвечают за проверку всех вкладов, что часто приводит к узким местам.

Чтобы увеличить шансы на рассмотрение вашего pull request, вы должны:

Ссылка на открытую проблему для нетривиальных изменений, чтобы прояснить цель PR
Убедитесь, что у вас есть соответствующие тесты. Это должно быть первой частью любого PR
Сохраняйте ваши pull request максимально простыми. Большие PR требуют больше времени на ревью
Убедитесь, что CI находится в зеленом состоянии. Рецензенты могут даже не смотреть в противном случае
Сохранить Обновление вашего запроса на слияние, либо по запросу, либо каждые несколько дней