Содействие проекту NumPy

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

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

Остальная часть этого документа посвящена работе с кодовой базой и документацией NumPy. Мы в процессе обновления описаний других задач и ролей. Если вас интересуют эти задачи, пожалуйста, свяжитесь с нами! Вы можете сделать это через список рассылки numpy-discussion, или на GitHub (создайте issue или оставьте комментарий к соответствующему issue). Это наши предпочтительные каналы связи (open source по своей природе!), но если вы предпочитаете сначала обсудить это в более приватном пространстве, вы можете сделать это в Slack (подробности см. на numpy.org/contribute).

Резюме процесса разработки

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

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

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

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

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

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

$ python -m pip install -r requirements/test_requirements.txt

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

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

$ spin test --coverage

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

$ firefox build/coverage/index.html

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

Для создания HTML документации используйте:

spin docs

Вы также можете запустить make из каталога doc . make help перечисляет все цели.

Чтобы получить необходимые зависимости и другие требования, см. Сборка API документации NumPy и справочной документации.

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

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

Процесс разработки NumPy описан в numpy-development-workflow.

Содействие проекту NumPy

Резюме процесса разработки

Рекомендации

Рекомендации по стилю

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

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

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