Содействие развитию 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 main
git pull upstream main
```
- Создайте ветвь для функции, над которой вы хотите работать. Поскольку имя ветви будет отображаться в сообщении о слиянии, используйте понятное имя, например, «ускорение linspace»:
```
git checkout -b linspace-speedups
```
- Локально делайте коммиты по мере вашего продвижения (git add и git commit). Используйте сообщение о коммите в правильном формате, напишите тесты, которые не проходят перед внесением изменений и проходят после, выполните все тесты локально. Обязательно документируйте любые изменения поведения в docstring, придерживаясь стандартного формата docstring 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/main` и вашей ветвью разработки

Если GitHub указывает, что ветвь вашего Pull Request больше не может быть автоматически объединена, вам необходимо включить изменения, внесённые с момента начала работы, в вашу ветвь. Рекомендуемый способ – rebase на ветке main.

Руководящие принципы

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

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

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

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

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

Требования

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

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

pip install -r doc_requirements.txt

END_OF_DOCUMENT_MARKER ```

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

git submodule update --init

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

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

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

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

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

Рабочий процесс, специфичный для NumPy, находится в numpy-development-workflow.