итератор.#

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

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

Мы понимаем, что у всех разный уровень опыта, кроме того, NumPy — довольно устоявшийся проект, поэтому трудно делать предположения об идеальном «первом контрибьюторе». Поэтому мы не помечаем issues меткой «good-first-issue». Вместо этого вы найдете проблемы с меткой "Sprintable". Эти проблемы могут быть:

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

Кроме того, в зависимости от вашего предыдущего опыта, некоторые "Sprintable" задачи могут быть лёгкими, в то время как другие могут оказаться для вас более сложными.

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

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

Вот краткое содержание, полные ссылки на оглавление ниже:

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

В исходном коде обязательно предваряйте любую ссылку на issue или PR gh-xxxx.

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

Руководства#

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

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

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

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

Pull requests (PRs), которые изменяют код, должны либо иметь новые тесты, либо изменять существующие тесты, чтобы они падали до 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.