Содействие в разработке NumPy

Не программист? Не проблема! NumPy многогранен, и нам нужна ваша помощь. Вот список задач, в которых мы нуждаемся (все они важны, поэтому упорядочены в алфавитном порядке):

Техническое обслуживание и разработка кода
Координация сообщества
DevOps
Разработка образовательного контента и описательной документации
Fundraising
Маркетинг
Управление проектами
Перевод контента
Дизайн и разработка веб-сайта
Написание технической документации

В остальной части этого документа рассматривается работа с кодовой базой и документацией NumPy. Мы сейчас обновляем описания других задач и ролей. Если вы заинтересованы в других задачах, свяжитесь с нами! Вы можете сделать это через почтовую рассылку numpy-discussion или на GitHub (откройте вопрос или оставьте комментарий к соответствующему вопросу). Это наши предпочтительные каналы связи (открытый исходный код по своей природе открыт!), однако, если вы предпочитаете сначала обсудить в частном порядке, обратитесь к нашим координаторам сообщества по адресу numpy-team@googlegroups.com или numpy-team.slack.com (отправьте письмо по адресу numpy-team@googlegroups.com для получения приглашения в первый раз).

Процесс разработки — краткое изложение

Вот краткое изложение, полные ссылки TOC находятся ниже:

Если вы впервые участвуете в разработке:
- Перейдите на https://github.com/numpy/numpy и нажмите кнопку «fork», чтобы создать свою копию проекта.
- Клонируйте проект на свой локальный компьютер:
```
git clone https://github.com/your-username/numpy.git
```
- Изменить каталог:
```
cd numpy
```
- Добавить удаленный репозиторий:
```
git remote add upstream https://github.com/numpy/numpy.git
```
- Теперь git remote -v отобразит два удаленных репозитория с названиями:
  - upstream, который ссылается на репозиторий numpy
  - origin, который ссылается на вашу персональную вилку
Разработка вашего вклада:
- Получить последние изменения из upstream:
```
git checkout master
git pull upstream master
```
- Создайте ветвь для функции, над которой вы хотите работать. Так как имя ветви будет отображаться в сообщении о слиянии, используйте осмысленное имя, например, «ускорение linspace»:
```
git checkout -b linspace-speedups
```
- Локально фиксируйте изменения по мере их внесения (git add и git commit) Используйте правильно отформатированное сообщение о фиксации, напишите тесты, которые завершаются неудачей до вашего изменения и проходят после него, запустите все тесты локально. Обязательно документируйте любые изменения в поведении в docstrings, придерживаясь стандартной документации NumPy стандарт.
Отправка вашего вклада:
- Отправьте свои изменения обратно в свою вилку на GitHub:
```
git push origin linspace-speedups
```
- Введите свое имя пользователя и пароль GitHub (постоянные участники или опытные пользователи могут удалить этот шаг, подключившись к GitHub с помощью SSH).
- Перейдите на GitHub. Новая ветвь отобразится с зеленой кнопкой «Запрос на вытягивание». Убедитесь, что заголовок и сообщение понятны, лаконичны и самодостаточны. Затем нажмите кнопку для отправки.
- Если ваше изменение вносит новую функцию или изменяет функциональность, опубликуйте сообщение на списке рассылки для объяснения внесенных изменений. В случае исправления ошибок, обновлений документации и т. д. это обычно не требуется, но если вы не получите никакой реакции, не стесняйтесь попросить о проверке.
Процесс проверки:
- Рецензенты (другие разработчики и заинтересованные члены сообщества) оставят комментарии к вашему запросу на вытягивание (PR) для улучшения реализации, документации и стиля. Каждый разработчик, работающий над проектом, проходит проверку кода, и мы пришли к выводу, что это дружеская беседа, в которой мы все учимся, а общее качество кода улучшается. Поэтому, пожалуйста, не позволяйте обзору отбить у вас желание внести свой вклад: его единственная цель — улучшить качество проекта, а не критиковать (мы, в конце концов, очень благодарны за ваше время, которое вы уделяете!). Для получения дополнительной информации см. наши Рекомендации для рецензентов.
- Для обновления вашего PR внесите изменения в свой локальный репозиторий, зафиксируйте их, **выполните тесты, и только если они пройдут успешно**, отправьте их в свою вилку. Как только эти изменения будут отправлены (в ту же ветвь, что и раньше), PR будет обновлен автоматически. Если вы не знаете, как исправить ошибки в тестах, вы можете все равно отправить свои изменения и попросить помощи в комментарии к PR.
- После каждого обновления PR запускаются различные службы непрерывной интеграции (CI) для сборки кода, выполнения модульных тестов, измерения покрытия кода и проверки стиля кодирования вашей ветви. Тесты CI должны пройти успешно, прежде чем ваш PR сможет быть объединен. Если CI завершается неудачей, вы можете узнать причину, нажав на значок «неудачно» (красный крест) и изучив журналы сборки и тестирования. Чтобы избежать чрезмерного использования и потерь ресурсов, проверьте свою работу локально, прежде чем фиксировать изменения.
- PR должен быть **утвержден** по крайней мере одним членом основной команды, прежде чем быть объединенным. Утверждение означает, что член основной команды тщательно проверил изменения, и PR готов к слиянию.
Документирование изменений

Помимо изменений в docstring функции и возможного описания в общей документации, если ваше изменение вносит какие-либо изменения, видимые пользователю, их необходимо упомянуть в примечаниях к выпуску. Чтобы добавить ваше изменение в примечания к выпуску, вам нужно создать небольшой файл с кратким описанием и поместить его в doc/release/upcoming_changes. Файл doc/release/upcoming_changes/README.rst содержит подробности о формате и соглашениях об именовании файлов.

Если ваше изменение вводит устаревание, сначала обсудите это на GitHub или на списке рассылки. Если достигнуто соглашение об устаревании, следуйте политике устаревания NEP 23, чтобы добавить устаревание.
Перекрестная ссылка на проблемы

Если PR относится к каким-либо проблемам, вы можете добавить текст xref gh-xxxx , где xxxx — номер проблемы на GitHub в комментариях. Аналогично, если PR решает проблему, замените xref на closes, fixes или любой другой вариант, который принимает GitHub.

В исходном коде убедитесь, что любая ссылка на проблему или PR начинается с gh-xxxx

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

Расхождения между `upstream/master` и вашей ветвью функций

Если GitHub указывает, что ветвь вашего запроса на вытягивание больше не может быть автоматически объединена, вам нужно включить изменения, внесенные с момента начала работы, в свою ветвь. Наш рекомендуемый способ сделать это — перебазировать на master.

Покрытие тестами

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

Для запуска набора тестов NumPy локально требуются дополнительные пакеты, такие как pytest и hypothesis. Дополнительные зависимости для тестирования перечислены в test_requirements.txt в корневом каталоге и удобно устанавливаются с помощью:

pip install -r test_requirements.txt

Тесты для модуля должны, в идеале, охватывать весь код в этом модуле, т. е. покрытие инструкций должно быть 100%.

Для измерения покрытия тестами установите pytest-cov, а затем выполните:

$ python runtests.py --coverage

Это создаст отчет в build/coverage, который можно просмотреть с помощью:

$ firefox build/coverage/index.html

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

Для сборки документации выполните make из каталога doc. make help перечисляет все цели. Например, для сборки HTML-документации можно выполнить:

make html

Затем все HTML-файлы будут сгенерированы в doc/build/html/. Поскольку документация основана на docstrings, соответствующая версия numpy должна быть установлена в хостовом Python, используемом для запуска Sphinx.

Требования

Sphinx необходим для сборки документации. Также требуются Matplotlib, SciPy и IPython.

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

pip install -r doc_requirements.txt

Документация numpy также зависит от расширения sphinx numpydoc, а также от внешней темы sphinx. Эти расширения включены в качестве подмодулей git и должны быть инициализированы перед построением документации. Из каталога doc/:

git submodule update --init

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

Устранение предупреждений

«ссылка не найдена: R###» Возможно, после ссылки в первой строке документации стоит знак подчёркивания (например, [1]_). Используйте этот метод для поиска исходного файла: $ cd doc/build; grep -rin R####
«Повторяющаяся ссылка R###, другой экземпляр в…» Возможно, в одной из документаций есть [2] без [1]

Детали процесса разработки

Остальная часть истории

Уникальный для NumPy процесс разработки описан в numpy-процесс-разработки.