Scrapyへの貢献

重要

https://docs.scrapy.org/en/master/contributing.html で、この文書の最新バージョンを読んでいることを再確認してください

Scrapyに貢献する方法はたくさんあります。 それらのいくつかを次に示します:

  • Scrapyについてのブログ。Scrapyの使用方法を世界中に伝えましょう。これは、より多くの例により新規参入者を助け、Scrapyプロジェクトの可視性を高めるのに役立ちます。

  • 以下の「バグの報告」(Reporting bugs)で詳述されているガイドラインに従うようにして、バグを報告し、 issue tracker で機能をリクエストします。

  • 新しい機能やバグ修正のためのパッチを上げてください。パッチの作成方法と送信方法の詳細については、下記の パッチを書く と 「パッチの送信」(Submitting patch) をお読みください。

  • Scrapy subreddit に参加して、Scrapyの改善方法に関するアイデアを共有してください。私たちは常に提案を受け入れています。

  • Stack Overflow でScrapyの質問に答えてください。

バグの報告

注釈

セキュリティの問題は scrapy-security@googlegroups.comにのみ 報告してください。これは信頼できるScrapy開発者のみが利用できるプライベートメーリングリストであり、そのアーカイブは公開されていません。

よく書かれたバグレポートは非常に役立ちます。よって、新しいバグを報告するときは以下のガイドラインに留意してください。

  • 最初に FAQ(よくある質問と回答) をチェックして、よく知られている質問で問題が解決されていないかどうかを確認してください

  • あなたがScrapyの使用に関する一般的な質問がある場合は、 Stack Overflow (scrapy タグ付け) で質問してください。

  • open issues をチェックして、問題がすでに報告されているかどうかを確認します。報告されている場合は、そのレポートを閉じないで、チケットの履歴とコメントを確認してください。追加の有用な情報がある場合は、コメントを残すか、修正を含めて プル・リクエスト を送信することを検討してください。

  • scrapy-users リストと Scrapy subreddit を検索して、そこで議論されているか、表示されているものがバグかどうかわからないかどうかを確認します。 #scrapy IRCチャンネルで質問することもできます。

  • 完全で再現可能な特定のバグレポート を作成します。テストケースが小さければ小さいほど良いです。他の開発者にはバグを再現するプロジェクトがないため、再現に必要なすべての関連ファイルを含めてください。たとえば、問題を示す「最小限の、完全な、検証可能な例」を作成するStackOverflowのガイド(Minimal, Complete, and Verifiable example)を参照してください。

  • 完全で再現可能な例を提供する最も素晴らしい方法は、Scrapyテスト・スイートに失敗したテスト・ケースを追加するプル・リクエストを送信することです( パッチの送信 参照)。これは、自分で問題を解決する意図がない場合でも役立ちます。

  • scrapy version -v の出力を含めると、バグに取り組んでいる開発者は、それが発生したバージョンとプラットフォームを正確に知ることができます。これは、バグを再現したり、すでに修正されているかどうかを知るのに非常に役立ちます。

パッチを書く

パッチが適切に作成されるほど、パッチが受け入れられる可能性が高くなり、マージが早くなります。

適切なパッチは以下のようにすべきです:

  • 特定の変更に必要な最小限のコードが含まれています。小さなパッチは、確認とマージが簡単です。したがって、複数の変更(またはバグ修正)を行っている場合は、変更ごとに1つのパッチを提出することを検討してください。複数の変更を1つのパッチにまとめないでください。大きな変更については、パッチ・キュー(patch queue)の使用を検討してください。

  • すべての単体テストに合格させます。以下の「テストの実行」(Running tests)を参照してください。

  • 修正されたバグまたは追加された新しい機能をチェックする1つ(または複数)のテスト・ケースを含めます。以下の「テストの作成」(Writing tests)を参照してください。

  • パブリック(文書化された)APIを追加または変更する場合は、同じパッチに文書ントの変更を含めてください。以下の「文書ポリシー」(Documentation policies)を参照してください。

  • プライベートAPIを追加する場合は、 docs/conf.py` ``coverage_ignore_pyobjects 変数に正規表現を追加して、ドキュメント・カバレッジ・チェックから新しいプライベートAPIを除外してください。

    あなたのプライベートAPIが適切にスキップされているかどうかを確認するには、次のように文書カバレッジ・レポートを生成します:

    tox -e docs-coverage
    
  • 非推奨のコードを削除する場合は、最初に、非推奨を導入したリリースから少なくとも1年(12か月)が経過していることを確認してください。 非推奨に関するポリシー 参照。

パッチの送信

パッチを送信する最良の方法は、GitHubでプルリクエスト(pull request)を発行することです。オプションで最初に新しい問題を作成します。

修正された機能または新しい機能(それが何であるか、なぜ必要なのかなど)を忘れずに説明してください。含める情報が多いほど、コア開発者がパッチを理解し、受け入れやすくなります。

パッチを作成する前に新しい機能(またはバグ修正)について議論することもできますが、引数を説明し、主題にいくつかの追加の考えを入れたことを示す準備ができているパッチを用意しておくことは常に良いことです。適切な出発点は、GitHubでプル・リクエストを送信することです。それはあなたのアイデアを説明するのに十分単純であり、アイデアが検証され有用であることが証明された後、文書/テストを後で残すことができます。または、 Scrapy subreddit で会話を開始して、最初にアイデアについて話し合うこともできます。

しばしば、解決したい問題に対する既存のプル・リクエストが存在することがありますが、何らかの理由で停止します。多くの場合、プル・リクエストは正しい方向にありますが、変更はScrapyメンテナによってリクエストされ、元のプル・リクエストの作成者にはそれらに対処する時間がありませんでした。この場合、このプルリ・クエストを選択することを検討してください。元のプル・リクエストからのすべてのコミットと、発生した問題に対処するための追加の変更を含む新しいプル・リクエストを開きます。そうすることは非常に役立ちます。元の作者のコミットが認識されるやいなや、彼/彼女のそのコミットを取り込むことは失礼とはみなされません。

既存のプルリクエストをローカル・ブランチにプルするには、 git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE を実行します(「upstream」をscrapyリポジトリのリモート名に、「$ PR_NUMBER」をプル・リクエストのID、びローカルに作成するブランチの名前を含む $BRANCH_NAME_TO_CREATE )。 https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally#modifying-an-inactive-pull-request-locally も参照してください。

GitHubプル・リクエストを作成するときは、タイトルを短く、しかし説明的なものにしてください。例えば、バグ #411:"Scrapy hangs if an exception raises in start_requests" の場合 "Fix for #411" より "Fix hanging when exception occurs in start_requests (#411)" が好ましいです。完全なタイトルを使用すると、issue trackerを簡単に確認できます。

最後に、機能的な変更とは別のコミットで、審美的な変更( PEP 8 対応、未使用のインポートの削除など)を維持するようにしてください。これにより、プル・リクエストの確認が容易になり、マージされる可能性が高くなります。

コーディング・スタイル

Scrapyに含めるコードを記述するときは、これらのコーディング規則に従ってください:

  • 特に指定がない限り、 PEP 8 に従ってください。

  • コードの可読性を向上させるためであれば、79文字より長い行を使用しても構いません。

  • 貢献するコードにあなたの名前を入れないでください。gitは、コードの作成者を識別するのに十分なメタ・データを提供します。セットアップ手順については、 https://help.github.com/en/github/using-git/setting-your-username-in-git を参照してください。

文書ポリシー

APIメンバー(クラス、メソッドなど)のリファレンス文書については、docstringsを使用し、Sphinx文書が autodoc 拡張を使用してdocstringを引用することを確認してください。APIリファレンス文書はdocstringの規則( PEP 257 )に準拠し、IDEにフレンドリである必要があります。つまりそれは簡潔な要点と例で書く必要があります。

チュートリアルやトピックなどの他の種類のドキュメントは、 docs/ ディレクトリ内のファイルでカバーする必要があります。これには、APIメンバーに固有の文書が含まれますが、それはAPIリファレンス文書を超える解説内容のものです。

いずれにせよ、docstringで何かが網羅されている場合、 docs/ ディレクトリ内のファイルにdocstringを複製するのではなく、 autodoc 拡張を使用してdocstringを文書に取り込みます。

新機能または変更された機能を対象とする文書の更新では、Sphinxの versionaddedversionchanged ディレクティブを使用する必要があります。 バージョンとして VERSION を使用します。対応するリリースの直前の実際のバージョンに置き換えます。 Scrapyの新しいメジャーバージョンまたはマイナーバージョンをリリースする際、我々はこれらのディレクティブのうち、3年以上経過しているディレクティブを削除します。

非推奨の機能に関する文書は、新しい読者が遭遇しないように削除する必要があります。非推奨への追加と非推奨の削除については、 リリース・ノート に記載されています。

テスト

テストは、 Twisted ユニットテスト フレームワーク を使用して実装されます。 テストを実行するには、 tox が必要です。

テストを実行する

全てのテストを実行するには:

tox

特定のテスト(たとえば tests/test_loader.py)を実行するには、次を使用します:

tox -- tests/test_loader.py

特定の tox 環境でテストを実行するには、 tox.ini からの環境名で -e <name> を使用します。たとえば、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 プラグインを使用することもできます。たとえば、すべてのCPUコアを使用してPython 3.6 tox 環境ですべてのテストを実行するには次のようにします:

tox -e py36 -- scrapy tests -n auto

カバレッジ・レポートを表示するには、 coverage をインストール( pip install coverage )して実行します:

coverage report

htmlまたはxmlレポートなどのオプションについては、 coverage --help の出力を参照してください。

テストを書く

すべての機能(新機能やバグ修正を含む)に期待どおりに動作することを確認するテストケースを含める必要があります。パッチをより早く受け入れてもらいたい場合は、パッチのテストを含めてください。

Scrapyはユニット・テストを使用します。ユニット・テストは tests/ ディレクトリにあります。それらのモジュール名は通常、テストしているモジュールの完全なパスに似ています。たとえば、アイテム・ローダーのコードは次の通りです:

scrapy.loader

そして、それらのユニットテストは以下です:

tests/test_loader.py