Содействие в NumPy

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

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

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

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

Вот краткое описание. Полные ссылки на содержание расположены ниже:

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

Стилевые рекомендации

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

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

Запросы на объединение (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-процесс-разработки.