Содействие развитию 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
```
- Добавьте репозиторий upstream:
```
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-speedups»:
```
git checkout -b linspace-speedups
```
- Осуществляйте локальные коммиты по мере продвижения (git add и git commit) Используйте сообщение коммита в правильном формате, напишите тесты, которые не проходят до внесения изменений, а после - проходят. Запустите все тесты локально. Обязательно документируйте любые изменения в поведении в строках документации, следуя стандартному формату документации NumPy.
Для отправки своего вклада:
- Отправьте свои изменения обратно на свою вилку на GitHub:
```
git push origin linspace-speedups
```
- Введите имя пользователя и пароль GitHub (повторяющиеся участники или продвинутые пользователи могут удалить этот шаг, подключившись к GitHub с помощью SSH).
- Перейдите на GitHub. Новая ветка будет отображаться с зеленой кнопкой «Pull Request». Убедитесь, что заголовок и сообщение ясны, лаконичны и понятны сами по себе. Затем нажмите кнопку, чтобы отправить ее.
- Если ваш коммит вносит новую функцию или изменяет функциональность, опубликуйте сообщение на почтовый список, чтобы объяснить свои изменения. Для исправлений ошибок, обновлений документации и т. д. это обычно не требуется, хотя, если вы не получите никакой реакции, не стесняйтесь запросить обзор.
Процесс проверки:
- Рецензенты (другие разработчики и заинтересованные члены сообщества) оставят комментарии в строках и/или общие комментарии к вашему Pull Request (PR), чтобы помочь вам улучшить его реализацию, документацию и стиль. Каждый разработчик, работающий над проектом, проходит проверку своего кода, и мы пришли к выводу, что это дружеская беседа, из которой все мы учимся, и в целом качество кода улучшается. Поэтому, пожалуйста, не позволяйте рецензированию отбить у вас желание участвовать: его единственная цель — повысить качество проекта, а не критиковать (в конце концов, мы очень благодарны за то время, которое вы жертвуете!).
- Для обновления вашего PR внесите изменения в локальный репозиторий, выполните коммит, проверьте тесты, и только если они пройдут успешно, отправьте их на вашу вилку. Как только эти изменения будут отправлены (в ту же ветку, что и раньше), PR будет обновлен автоматически. Если вы не знаете, как исправить сбои тестов, вы можете отправить свои изменения и запросить помощь в комментарии PR.
- После каждого обновления PR запускаются различные службы непрерывной интеграции (CI) для сборки кода, запуска модульных тестов, измерения покрытия кода и проверки стиля кода вашей ветки. Тесты CI должны пройти успешно, прежде чем ваш PR может быть объединен. Если CI завершится сбоем, вы можете узнать причину, нажав на значок «неудачно» (красный крест) и просмотрев журнал сборки и тестов.
- PR должен быть утвержден как минимум одним членом основной команды разработчиков, прежде чем он может быть объединен. Утверждение означает, что член основной команды тщательно проверил изменения и PR готов к слиянию.
Документировать изменения

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

Стилистические рекомендации

Настройте свой редактор для соблюдения PEP 8 (удаление хвостовых пробелов, отсутствие табуляции и т. д.). Проверьте код с помощью pyflakes/flake8.
Используйте типы данных numpy вместо строк (np.uint8 вместо "uint8").
Используйте следующие соглашения импорта:
```
import numpy as np
```
Для кода C см. руководство по стилю NumPy-C

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

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

Тесты для модуля должны, в идеале, охватывать весь код этого модуля, т. е. покрытие операторов должно составлять 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/. Так как документация основана на строках документации, соответствующая версия numpy должна быть установлена в хостовом python, используемом для запуска sphinx.

Требования

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

Исправление предупреждений

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

Процесс разработки - подробности

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

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