Способы внести вклад#

Этот документ призван дать обзор способов внесения вклада в SciPy. Он пытается ответить на часто задаваемые вопросы и предоставить некоторое представление о том, как процесс сообщества работает на практике. Читатели, знакомые с сообществом SciPy и опытные программисты на Python, могут сразу перейти к Руководство для участников SciPy.

Есть много способов внести вклад:

  • Внесение нового кода

  • Исправление ошибок, улучшение документации и другие работы по поддержке

  • Проверка открытых pull requests

  • Триажирование проблем

  • Работа над scipy.org веб-сайт

  • Ответы на вопросы и участие в форум.

Внесение нового кода#

Если вы работали со стеком научных инструментов Python какое-то время, вы, вероятно, имеете некоторый код, о котором думаете: «это может быть полезно и для других». Возможно, тогда хорошей идеей будет внести его в SciPy или другой проект с открытым исходным кодом. Первый вопрос, который нужно задать: куда принадлежит этот код? На этот вопрос сложно ответить здесь, поэтому мы начнем с более конкретного: какой код подходит для включения в SciPy? Почти весь новый код, добавленный в SciPy, объединяет то, что он потенциально полезен в нескольких научных областях и вписывается в рамки существующих подпакетов SciPy (см. Принятие решений о новых функциях). В принципе, новые подпакеты тоже могут быть добавлены, но это гораздо менее распространено. Для кода, который специфичен для одного приложения, может существовать проект, который может использовать этот код. Некоторые SciKits (scikit-learn, scikit-image, statsmodels, и т.д.) являются хорошими примерами здесь; они имеют более узкую направленность и из-за этого больше предметно-ориентированного кода, чем SciPy.

Теперь, если у вас есть код, который вы хотели бы включить в SciPy, как вы это делаете? После проверки, что ваш код может распространяться в SciPy под совместимой лицензией (см. Вопросы лицензирования), первый шаг — обсудить это на scipy-dev форум. Все новые функции, а также изменения в существующем коде обсуждаются и принимаются там. Вы можете, и, вероятно, должны начать это обсуждение до завершения вашего кода. Помните, что для добавления в SciPy ваш код должен быть проверен кем-то другим, поэтому постарайтесь найти кого-то, кто готов проверить вашу работу, пока вы над ней работаете.

Предполагая результат обсуждения на форум положительно, и у вас есть функция или фрагмент кода, который делает то, что вам нужно, что дальше? Прежде чем код будет добавлен в SciPy, он должен иметь хорошую документацию, модульные тесты, бенчмарки и правильный стиль кода.

  1. Модульные тесты

    В принципе, вы должны стремиться создавать модульные тесты, которые проверяют весь код, который вы добавляете. Это даёт некоторую уверенность в том, что ваш код работает правильно, также на версиях Python и аппаратном или программном обеспечении, которые у вас нет в наличии. Подробное описание того, как писать модульные тесты, приведено в Рекомендации по тестированию, и Локальный запуск тестов SciPy документирует, как их запускать.

  2. Бенчмарки

    Модульные тесты проверяют корректность функциональности; бенчмарки измеряют производительность кода. Не весь существующий код SciPy имеет бенчмарки, но должен: по мере роста SciPy становится все более важным отслеживать время выполнения, чтобы выявлять неожиданные регрессии. Дополнительная информация о написании и запуске бенчмарков доступна в Бенчмаркинг SciPy с помощью airspeed velocity.

  3. Документация

    Четкая и полная документация необходима, чтобы пользователи могли находить и понимать код. Документация для отдельных функций и классов — которая включает как минимум базовое описание, тип и значение всех параметров и возвращаемых значений, а также примеры использования в doctest формат – помещается в docstrings. Эти docstrings можно читать в интерпретаторе, и они компилируются в справочное руководство в форматах HTML и pdf. Высокоуровневая документация для ключевых (областей) функциональности предоставляется в формате учебника и/или в docstrings модулей. Руководство по написанию документации приведено в Стиль документации, и Локальная сборка документации с помощью Sphinx объясняет, как предварительно просмотреть документацию в том виде, в котором она будет отображаться онлайн.

  4. Стиль кода

    Единый стиль кода облегчает чтение вашего кода другими. SciPy следует стандартным рекомендациям по стилю Python, PEP8, за исключением того, что рекомендуемая максимальная длина строки составляет 88 символов, а не 79 символов, как в PEP8.

    Мы предоставляем git pre-commit hook, который может проверять каждый ваш коммит на соответствие стилю. Установите его (однократно), запустив следующую команду из корня репозитория SciPy:

    cp tools/pre-commit-hook.py .git/hooks/pre-commit

    В качестве альтернативы вы можете запустить линтер вручную:

    python dev.py lint

    Большинство IDE и текстовых редакторов также имеют настройки, которые могут помочь вам следовать PEP8, например, заменяя табуляции четырьмя пробелами. Дополнительная информация доступна в PEP8 и SciPy.

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

Другой вопрос, который может у вас возникнуть: куда именно поместить мой код? Чтобы ответить на этот вопрос, полезно понять, как определён публичный API SciPy (интерфейс программирования приложений). Для большинства модулей API имеет два уровня глубины, что означает, что ваша новая функция должна отображаться как scipy.subpackage.my_new_func. my_new_func может быть помещён в существующий или новый файл в /scipy//, его имя добавляется в __all__ списка в этом файле (который перечисляет все публичные функции в файле), и эти публичные функции затем импортируются в /scipy//__init__.py. Любые приватные функции/классы должны иметь ведущее подчеркивание (_) в их названии. Более подробное описание того, что представляет собой публичный API SciPy, дано в API SciPy.

Как только вы считаете, что ваш код готов для включения в SciPy, вы можете отправить pull request (PR) на Github. Мы не будем вдаваться в детали работы с git здесь, это хорошо описано в Git для разработки и на Страницы помощи Github. При отправке PR для новой функции обязательно упомяните об этом также в scipy-dev форум. Это может побудить заинтересованных людей помочь с рецензированием вашего PR. Предполагая, что вы уже получили положительный отзыв ранее по общей идее вашего кода/функции, цель рецензирования кода — убедиться, что код корректен, эффективен и соответствует требованиям, изложенным выше. Во многих случаях рецензирование кода происходит относительно быстро, но возможно, что оно застопорится. Если вы уже учли всю предоставленную обратную связь, вполне допустимо спросить на форум снова для проверки (после разумного промежутка времени, например, пары недель). После завершения проверки PR объединяется в основную ветку SciPy.

Выше описаны требования и процесс добавления кода в SciPy. Однако это ещё не отвечает на вопрос о том, как именно принимаются решения. Основной ответ: решения принимаются консенсусом всеми, кто участвует в обсуждении на форум. Это включает разработчиков, других пользователей и вас самих. Стремление к консенсусу в обсуждении важно — SciPy — это проект для научного сообщества Python и созданный им. В тех редких случаях, когда согласие не может быть достигнуто, сопровождающие соответствующего модуля могут решить вопрос.

Вопросы лицензирования#

Я основал свой код на существующем коде Matlab/R/…, найденном онлайн, это нормально?

Зависит. SciPy распространяется под лицензией BSD, поэтому если код, на котором вы основали свой код, также лицензирован под BSD или имеет совместимую с BSD лицензию (например, MIT, PSF), то это допустимо. Код, который лицензирован под GPL или Apache, не имеет чёткой лицензии, требует цитирования или бесплатен только для академического использования, не может быть включён в SciPy. Следовательно, если вы скопировали существующий код с такой лицензией или сделали прямой перевод его на Python, ваш код не может быть включён. Если вы не уверены, пожалуйста, спросите на scipy-dev форум.

Почему SciPy использует лицензию BSD, а не, например, GPL?

Как и Python, SciPy использует «разрешительную» лицензию с открытым исходным кодом, которая позволяет проприетарное повторное использование. Хотя это позволяет компаниям использовать и изменять программное обеспечение, не возвращая ничего взамен, считается, что более широкая пользовательская база приводит к большему количеству вкладов в целом, и компании часто публикуют свои модификации в любом случае, без обязательств. См. John Hunter’s BSD pitch.

Для получения дополнительной информации о лицензии SciPy см. Лицензирование.

Поддержка существующего кода#

Предыдущий раздел говорил конкретно о добавлении новой функциональности в SciPy. Большая часть этого обсуждения также применима к поддержке существующего кода. Поддержка означает исправление ошибок, улучшение качества кода, лучшее документирование существующей функциональности, добавление отсутствующих модульных тестов, добавление тестов производительности, поддержку скриптов сборки в актуальном состоянии и т.д. SciPy список задач содержит все сообщенные ошибки, проблемы со сборкой/документацией и т.д. Исправление проблем помогает улучшить общее качество SciPy, а также является хорошим способом ознакомиться с проектом. Вы также можете захотеть исправить ошибку, потому что столкнулись с ней и вам нужно, чтобы соответствующая функция работала правильно.

Обсуждение стиля кода и модульного тестирования выше в равной степени применимо к исправлениям ошибок. Обычно лучше начать с написания модульного теста, который демонстрирует проблему, т.е. он должен проходить, но не проходит. После этого можно исправить код так, чтобы тест проходил. Этого должно быть достаточно для отправки PR по этой проблеме. В отличие от добавления нового кода, обсуждение этого на форум может быть необязательным - если старое поведение кода явно некорректно, никто не будет возражать против его исправления. Может потребоваться добавить предупреждение или сообщение об устаревании для изменённого поведения. Это должно быть частью процесса рецензирования.

Примечание

Pull requests, которые only изменения стиля кода, например, исправление некоторых проблем PEP8 в файле, не рекомендуются. Такие PR часто не стоят загромождения истории git annotate, и отнимают время рецензента, которое можно было бы потратить лучше. Очистка стиля кода, который затрагивается как часть функционального изменения, однако допустима.

Проверка pull requests#

Проверка открытых запросов на включение (PR) очень приветствуется и является ценным способом помочь увеличить скорость продвижения проекта. Если у вас есть конкретные знания/опыт в определённой области (например, «алгоритмы оптимизации» или «специальные функции»), то проверка PR в этой области особенно ценна - иногда PR с техническим кодом приходится долго ждать слияния из-за нехватки подходящих рецензентов.

Мы призываем всех участвовать в процессе рецензирования; это также отличный способ ознакомиться с кодом. Рецензентам следует задать себе некоторые или все из следующих вопросов:

  • Было ли это изменение адекватно обсуждено (актуально для новых функций и изменений в существующем поведении)?

  • Научно ли обоснована функция? Алгоритмы могут быть известны как работающие на основе литературы; в противном случае, более пристальный взгляд на корректность ценен.

  • Ясно ли предполагаемое поведение при всех условиях (например, неожиданные входные данные как пустые массивы или значения nan/inf)?

  • Соответствует ли код ожиданиям по качеству, тестированию и документации, изложенным в Внесение нового кода?

Если мы вас ещё не знаем, рассмотрите возможность представиться.

Другие способы внести вклад#

Есть много способов внести вклад, помимо написания кода.

Триажирование проблем (исследование отчётов об ошибках на валидность и возможные действия для принятия) также является полезной деятельностью. В SciPy есть сотни открытых проблем; закрытие недействительных и правильная маркировка действительных (в идеале с некоторыми первыми мыслями в комментарии) позволяет расставлять приоритеты в работе по обслуживанию и легко находить связанные проблемы при работе с существующей функцией или подпакетом. Чтобы узнать больше о триажировании проблем, см. Триажирование и курирование проблем.

Участие в обсуждениях на scipy-user и scipy-dev форум является вкладом сам по себе. Каждый, кто пишет в эти списки с проблемой или идеей, хотел бы получить ответы, и написание таких ответов делает проект и сообщество более функциональными и гостеприимными.

The scipy.org веб-сайт содержит много информации как о проекте SciPy, так и о сообществе SciPy, и ему всегда могут пригодиться новые руки. Исходный код веб-сайта находится в отдельном репозитории: scipy/scipy.org

Начало работы#

Спасибо за интерес к участию в разработке SciPy! Если вы хотите внести код, мы надеемся, что вы продолжите к Руководство для участников SciPy для получения подробной информации о настройке среды разработки, реализации улучшений и отправке первого PR!