Рекомендации для рецензентов

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

Кто может быть рецензентом?

Рецензии могут поступать и извне команды NumPy – мы приветствуем вклад экспертов в предметной области (например, linalg или fft) или разработчиков других проектов. Вам не нужно быть участником команды NumPy (членом команды NumPy с правом слияния PR) для рецензирования.

Если мы вас ещё не знаем, подумайте о том, чтобы представиться на списке рассылки или в Slack перед началом проверки запросов на добавление.

Рекомендации по общению

• Каждый PR, хороший или плохой, является актом щедрости. Начав с положительного комментария, вы поможете автору почувствовать себя вознагражденным, и ваши последующие замечания будут восприняты более внимательно. Вы тоже почувствуете себя лучше.
• Если возможно, начинайте с крупных проблем, чтобы автор понял, что его проблемы поняты. Избегайте немедленного анализа каждой строки или начала с мелких, распространенных проблем.
• Вы являетесь лицом проекта, и NumPy некоторое время назад решил, каким проектом он будет: открытым, чутким, гостеприимным, дружелюбным и терпеливым. Будьте добры к участникам.
• Не позволяйте совершенству быть врагом хорошего, особенно в отношении документации. Если вы обнаруживаете, что делаете много мелких предложений или слишком придирчивы к стилю или грамматике, рассмотрите возможность слияния текущего PR, когда все важные вопросы будут решены. Затем либо создайте коммит напрямую (если вы являетесь разработчиком), либо откройте новый PR.
• Если вам нужна помощь в написании ответов в рецензиях, ознакомьтесь со стандартными ответами для рецензирования.

Список проверок для рецензента

• Ясен ли предполагаемый результат при всех условиях? Следует обратить внимание на:

  • Что происходит с неожиданными входными данными, такими как пустые массивы или значения nan/inf?
  • Проверяются ли аргументы axis или shape на то, чтобы они были int или tuples?
  • Проверяются ли необычные dtypes, если функция поддерживает их?

• Нужно ли улучшить имена переменных для ясности или согласованности?
• Нужно ли добавить или удалить комментарии, которые бесполезны или избыточны?
• Соответствует ли документация Рекомендациям NumPy? Правильно ли отформатированы строковые литералы документации?
• Соответствует ли код Рекомендациям NumPy по стилю?
• Если вы являетесь разработчиком, и это не очевидно из описания PR, добавьте в сообщение о слиянии краткое объяснение того, что делал ответвление, и, если вы закрываете ошибку, добавьте также «Закрывает issue #123», где 123 – номер ошибки.
• Для изменений в коде, по крайней мере, один разработчик (т. е. человек с правами коммита) должен просмотреть и одобрить запрос на добавление. Если вы первый просмотрели PR и одобрили изменения, используйте инструмент GitHub одобрения рецензии для маркировки как такового. Если PR прост, например, это очевидно правильная исправление ошибки, его можно объединить сразу. Если он более сложный или меняет публичный API, оставьте его открытым, по крайней мере, на пару дней, чтобы другие разработчики могли его просмотреть.
• Если вы последующий рецензент уже одобренного PR, используйте тот же метод рецензирования, что и для нового PR (сосредоточьтесь на более крупных проблемах, избегайте добавления только нескольких мелких замечаний). Если у вас есть права коммита, и вы считаете, что дальнейшего рецензирования не требуется, объедините PR.

Для разработчиков

• Убедитесь, что все автоматические тесты CI проходят, а построение документации происходит без ошибок.
• В случае конфликтов слияния попросите автора PR выполнить перебазирование на мастер.
• Для PR, добавляющих новые функции или имеющих другую сложность, подождите, по крайней мере, день-два, прежде чем объединять его. Таким образом, другие получат шанс прокомментировать перед внедрением кода. Подумайте о добавлении его в заметки к выпуску.
• При объединении вкладов разработчик несет ответственность за обеспечение того, что они соответствуют требованиям, изложенным в Руководстве по процессам разработки для NumPy. Кроме того, проверьте, что новые функции и изменения обратной совместимости обсуждались на списке рассылки numpy-discussion.
• Сжатие коммитов или очистка сообщений коммитов PR, которые вы считаете слишком беспорядочными, допустимо. Не забудьте сохранить имя первоначального автора при этом. Убедитесь, что сообщения коммитов следуют правилам NumPy.
• Когда вы хотите отклонить PR: если это очевидно, вы можете просто закрыть его и объяснить почему. Если нет, лучше сначала объяснить, почему вы считаете, что PR не подходит для включения в NumPy, а затем позволить второму разработчику прокомментировать или закрыть.

Процесс работы с GitHub

При рецензировании запросов на добавление, пожалуйста, используйте соответствующие функции отслеживания процессов в GitHub:

• После завершения рецензирования, если вы хотите попросить автора внести изменения, измените статус вашей рецензии на «Требуются изменения». Это можно сделать на странице GitHub, на вкладке «Измененные файлы», в разделе «Изменить отзывы» (кнопка в правом верхнем углу).
• Если вас устраивает текущее состояние, отметьте запрос на добавление как «Одобрено» (так же, как и «Требуются изменения»). В качестве альтернативы (для разработчиков): объедините запрос на добавление, если считаете, что он готов к слиянию.

Может быть полезно иметь копию кода запроса на добавление на собственном компьютере, чтобы вы могли с ним работать локально. Вы можете использовать GitHub CLI, нажав на кнопку Open with в правом верхнем углу страницы PR.

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