Внесение вклада в Scrapy

Важно

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

Есть много способов внести свой вклад в Scrapy. Вот некоторые из них:

  • Блог о Scrapy. Расскажите миру, как вы используете Scrapy. Это поможет новичкам с большим количеством примеров и поможет проекту Scrapy сделать его более заметным.

  • Сообщайте об ошибках и запрашивайте функции в issue трекере, стараясь следовать инструкциям, подробно описанным ниже.

  • Отправляйте патчи для новых функций и/или исправлений ошибок. Пожалуйста, прочитайте Написание патчей и Отправка патчей ниже, чтобы узнать, как написать и отправить патч.

  • Присоединяйтесь к Scrapy subreddit и поделитесь своими идеями о том, как улучшить Scrapy. Мы всегда открыты для предложений.

  • Ответьте на вопросы Scrapy на Stack Overflow.

Сообщение об ошибках

Примечание

Сообщайте о проблемах безопасности только на scrapy-security@googlegroups.com. Это частный список, открытый только для доверенных разработчиков Scrapy, и его архивы не являются общедоступными.

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

  • сначала прочитайте ЧЗВ, чтобы узнать, решена ли ваша проблема в известном вопросе

  • если у вас есть общий вопрос об использовании Scrapy, задаёт его по Stack Overflow (используйте тег «scrapy»).

  • проверите общие ошибки, чтобы узнать, не сообщалось ли уже о проблеме. Если да, не закрывайте отчёт, а проверить историю заявок и комментарии. Если у вас есть дополнительная полезная информация, оставьте комментарий, или рассмотрите отправка запроса на перенос с исправлением.

  • выполнить поиск по спискам scrapy-users и Scrapy subreddit, чтобы узнать, обсуждалось ли это там, или если вы не уверены, что то, что вы видите, является ошибкой. Вы также можете спросить в IRC-канале #scrapy.

  • пишите полные, воспроизводимые, конкретные отчеты об ошибках. Чем меньше тест случая, тем лучше. Помните, что у других разработчиков не будет вашего проекта чтобы воспроизвести ошибку, поэтому включите все соответствующие файлы, необходимые для его воспроизведения. См., например, руководство StackOverflow по созданию минимального»полного и поддающегося проверке примера, демонстрирующий проблему»

  • Самый замечательный способ предоставить полный воспроизводимый пример — это отправить запрос на перенос, который добавляет неудачный тестовый пример к набору тестирования Scrapy (см. Отправка патчей). Это полезно, даже если у вас нет намерения решать проблему самостоятельно.

  • включает вывод scrapy version -v, чтобы разработчики, работающие над вашей ошибкой, точно знали, на какой версии и платформе она возникла, что часто очень помогает при её воспроизведении или знании того, была ли она уже исправлена.

Написание патчей

Чем лучше написан патч, тем выше шансы, что он будет принят, и тем скорее он будет объединён.

Хорошо написанные патчи должны:

  • содержать минимальный объем кода, необходимый для конкретного изменения. Небольшие исправления легче просматривать и объединять. Итак, если вы вносите более одного изменения (или исправления ошибки), рассмотрите возможность отправки одного патча на каждое изменение. Не объединяйте несколько изменений в один патч. Для больших изменений рассмотрите возможность использования очереди исправлений.

  • пройти все юнит-тесты. См. Запуск тестов ниже.

  • включите один (или несколько) тестовых примеров, которые проверяют исправление ошибки или добавление новых функций. См. Написание тестов ниже.

  • если вы добавляете или изменяете общедоступный (документированный) API, включает изменения документации в тот же патч. См. Политики документации ниже.

  • если вы добавляете частный API, добавить регулярное выражение к переменной coverage_ignore_pyobjects docs/conf.py, чтобы исключить новый частный API из проверок покрытия документации.

    Чтобы увидеть, правильно ли пропущен ваш частный API, сгенерируйте отчёт о покрытии документации, как показано ниже:

    tox -e docs-coverage

  • если вы удаляете устаревший код, сначала убедиться, что прошел как минимум 1 год (12 месяцев) с момента релиза, в котором было объявлено устаревание. См. Политика устаревания.

Отправка патчей

Лучший способ отправить патч — выпустить pull request на GitHub, при необходимости сначала создав новую проблему.

Не забудьте объяснить, что было исправлено или новые функции (что это такое, зачем это нужно и т. д.). Чем больше информации вы укажете, тем проще будет разработчикам ядра понять и принять ваш патч.

Вы также можете обсудить новую функциональность (или исправление ошибки) перед созданием патча, но всегда хорошо иметь готовый патч, чтобы проиллюстрировать ваши аргументы и показать, что вы дополнительно продумали эту тему. Хорошей отправной точкой является отправка запроса на перенос на GitHub. Это может быть достаточно просто, чтобы проиллюстрировать вашу идею и оставить документацию/тесты на потом, когда идея будет проверена и окажется полезной. Кроме того, вы можете начать разговор в Scrapy subreddit, чтобы сначала обсудить свою идею.

Иногда существует запрос на перенос для проблемы, которую вы хотите решить, но которая по какой-то причине зависает. Часто запрос на вытягивание идет в правильном направлении, но изменения запрашиваются разработчиками Scrapy, и автор исходного запроса на вытягивание не успел их рассмотреть. В этом случае подумайте о том, чтобы выбрать данный пул-реквест: открыть новый пул-реквест со всеми коммитами из исходного пул-реквеста, а также с дополнительными изменениями для решения поднятых проблем. Это очень помогает; это не считается грубым, если первоначальный автор признается, сохраняя свои коммиты.

Вы можете перетащить существующий запрос на перенос в локальную ветку, запустив git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE (заменить upstream на удаленное имя для репозитория scrapy, $PR_NUMBER на идентификатор запроса на вытягивание и $BRANCH_NAME_TO_CREATE на имя ветки, которую вы хотите создать локально).

При написании запросов на вытягивание на GitHub старайтесь, чтобы заголовки были короткими, но информативными. Например. Для ошибки #411: «Scrapy зависает, если возникает исключение в start_requests», предпочитайте «Исправить зависание при возникновении исключения в start_requests (#411)» вместо «Исправить для #411». Полные заголовки позволяют легко просматривать систему отслеживания проблем.

Наконец, постарайтесь сохранить эстетические изменения (соответствие pep 8, удаление неиспользуемых импортов и т. д.) В отдельных коммитах от функциональных изменений. Это упростит проверку запросов на вытягивание и повысит вероятность их объединения.

Стиль кодирования

Пожалуйста, следуйте этим соглашениям о кодировании при написании кода для включения в Scrapy:

  • Если не указано иное, следуйте pep 8.

  • Можно использовать строки длиннее 79 символов, если это улучшает читаемость кода.

  • Не указывайте свое имя в коде, который вы публикуете; git предоставляет достаточно метаданных, чтобы идентифицировать автора кода. См. https://help.github.com/en/github/using-git/setting-your-username-in-git для инструкций по установке.

Политика документации

Для справочной документации членов API (классов, методов и т. д.) Используйте строки документации и убедиться, что в документации Sphinx используется расширение autodoc для извлечения строк документации. Справочная документация по API должна соответствовать соглашениям о строках документации (PEP 257) и быть удобной для IDE: кратко, по существу, и она может содержать короткие примеры.

Другие типы документации, такие как учебные пособия или темы, должны быть включены в файлы в каталоге docs/. Сюда входит документация, относящаяся к члену API, но выходит за рамки справочной документации API.

В любом случае, если что-то покрыто строкой документации, используйте расширение autodoc, чтобы вставить строку документации в документацию, вместо того, чтобы дублировать строку документации в файлах в каталоге docs/.

Обновления документации, касающиеся новых или измененных функций, должны использовать директивы Sphinx versionadded и versionchanged. Используйте VERSION в качестве версии, мы заменим её актуальной версией прямо перед соответствующим выпуском. Когда мы выпускаем новую основную или вспомогательную версию Scrapy, мы удаляем данные директивы, если они старше 3 лет.

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

Тесты

Тесты реализованы с использованием Twisted фреймворка модульного тестирования. Для запуска тестов требуется tox.

Запуск тестов

Чтобы запустить все тесты:

tox

Для запуска конкретного теста (например, tests/test_loader.py) используйте:

tox -- tests/test_loader.py

Чтобы запустить тесты в определенной среде tox, используйте -e <name> с именем среды из tox.ini. Например, для запуска тестов с Python 3.6 используйте:

tox -e py36

Вы также можете указать список сред, разделенных запятыми, и использовать параллельный режим tox для параллельного запуска тестов в нескольких средах:

tox -e py36,py38 -p auto

Чтобы передать параметры командной строки в pytest, добавьте их после -- в свой вызов tox. Использование -- отменяет позиционные аргументы по умолчанию, определённые в tox.ini, поэтому вы также должны включить данные позиционные аргументы по умолчанию (scrapy tests) после --:

tox -- scrapy tests -x  # stop after first failure

Вы также можете использовать плагин pytest-xdist. Например, для запуска всех тестов в среде Python 3.6 tox с использованием всех ядер вашего процессора:

tox -e py36 -- scrapy tests -n auto

Чтобы просмотреть отчёт о покрытии, установите coverage (pip install coverage) и запустите:

coverage report

см. вывод coverage --help для получения дополнительных параметров, таких как отчёт html или xml.

Написание тестов

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

Scrapy использует модульные тесты, которые находятся в каталоге tests/. Их имя модуля обычно соответствует полному пути к модулю, который они тестируют. Например, код загрузчика элементов находится в формате:

scrapy.loader

И их юнит-тесты:

tests/test_loader.py