寄稿者ガイド
これを読んでいるなら、おそらくリクエストに貢献することに興味があるでしょう。 どうもありがとうございます! オープンソースプロジェクトは、他の人から受けたサポートに基づいて生き生きと死にます。リクエストプロジェクトへの貢献を検討しているという事実は、非常に寛大です。
このドキュメントは、このプロジェクトに貢献するためのガイドラインとアドバイスを示しています。 貢献することを考えている場合は、このドキュメントを読んで、このプロジェクトへの貢献がどのように機能するかを理解することから始めてください。 ご不明な点がございましたら、 Nate Prewitt 、 Ian Cordasco 、または Seth Michael Larson のいずれかにお気軽にお問い合わせください。
このガイドは、あなたが考えている貢献の種類に基づいてセクションに分かれており、すべての貢献者のための一般的なガイドラインをカバーするセクションがあります。
心を込めて
心を込めて、または途中で。 -ケネス・ライツ
リクエストには、バグの報告や機能のリクエストなど、あらゆる形態の貢献を管理する非常に重要なルールが1つあります。 この黄金のルールは、「誠実であるか、あなたの道を進んでいる」です。
関係者全員が敬意を持って扱われる限り、すべての貢献を歓迎します。
早期フィードバックを得る
あなたが貢献しているなら、それが完全に磨かれ、完成するまで、あなたの貢献に座る必要を感じないでください。 これは、関係者全員ができるだけ早くフィードバックを求めるのに役立ちます。 フィードバックのために投稿の初期の未完成バージョンを送信しても、その投稿が受け入れられる可能性が損なわれることはなく、プロジェクトに適さない投稿に多くの作業を費やす必要がなくなります。
貢献の適合性
私たちのプロジェクトメンテナは、寄付がリクエストに適しているかどうかについて最後の言葉を持っています。 すべての投稿は慎重に検討されますが、プロジェクトの現在の目標やニーズに合わないため、投稿が拒否されることがあります。
あなたの貢献が拒否されたとしても、絶望しないでください! これらのガイドラインに従っている限り、次の貢献が受け入れられる可能性がはるかに高くなります。
コードの貢献
コードを送信する手順
コードを提供するときは、次のチェックリストに従う必要があります。
- GitHubでリポジトリをフォークします。
- テストを実行して、すべてがシステムに合格していることを確認します。 そうでない場合は、失敗する理由を調査する必要があります。 これを自分で診断できない場合は、このドキュメントのガイドラインバグレポートに従って、バグレポートとして報告してください。
- バグや機能を実証するテストを作成します。 それらが失敗することを確認してください。
- 変更を加えます。
- テストスイート全体を再度実行し、追加したテストを含むすべてのテストがに合格することを確認します。
- GitHubプルリクエストをメインリポジトリの
master
ブランチに送信します。 GitHubプルリクエストは、このプロジェクトで期待されるコードコラボレーションの方法です。
次のサブセクションでは、上記のいくつかのポイントについて詳しく説明します。
コードレビュー
コントリビューションは、コードレビューが完了するまでマージされません。 強く反対しない限り、コードレビューのフィードバックを実装する必要があります。 コードレビューのフィードバックに反対する場合は、明確かつ冷静にケースを作成する必要があります。 その後、フィードバックが引き続き適用されると判断された場合は、フィードバックを適用するか、投稿を取り消す必要があります。
新しい貢献者
オープンソースを初めて使用する場合、または比較的新しい場合は、歓迎します。 Requestsは、オープンソースの世界を穏やかに紹介することを目的としています。 最善の貢献方法が心配な場合は、メンテナ(上記)にメールを送り、助けを求めることを検討してください。
早期フィードバックの取得セクションも確認してください。
ケネス・ライツのコードスタイル™
Requestsコードベースは、 PEP 8 コードスタイルを使用します。
PEP 8で概説されている標準に加えて、いくつかのガイドラインがあります。
- 行の長さは、都合のよい場合、79文字を超えて100文字にすることができます。
- 行の長さが100文字を超える可能性があります。そうしないと、ひどく不便になります。
- 常に一重引用符で囲まれた文字列を使用します(例:
'#flatearth'
)。ただし、文字列内で一重引用符が使用されている場合を除きます。
さらに、PEP8が行の継続に推奨するスタイルの1つは、すべての味覚を完全に欠いており、Requestsコードベース内で許可されていません。
# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
var_three, var_four)
いいえ。 しないでください。 お願いします。 これははるかに優れています:
foo = long_function_name(
var_one,
var_two,
var_three,
var_four,
)
Docstringは、次の構文に従う必要があります。
def the_earth_is_flat():
"""NASA divided up the seas into thirty-three degrees."""
pass
def fibonacci_spiral_tool():
"""With my feet upon the ground I lose myself / between the sounds
and open wide to suck it in. / I feel it move across my skin. / I'm
reaching up and reaching out. / I'm reaching for the random or
whatever will bewilder me. / Whatever will bewilder me. / And
following our will and wind we may just go where no one's been. /
We'll ride the spiral to the end and may just go where no one's
been.
Spiral out. Keep going...
"""
pass
すべての関数、メソッド、およびクラスにはdocstringが含まれています。 オブジェクトデータモデルメソッド(例: __repr__
)は通常、このルールの例外です。
世界をより良い場所にするためにご協力いただきありがとうございます。
ドキュメントの貢献
ドキュメントの改善はいつでも大歓迎です! ドキュメントファイルは、コードベースのdocs/
ディレクトリにあります。 それらは reStructuredText で書かれており、 Sphinx を使用してドキュメントの完全なスイートを生成します。
ドキュメントを寄稿するときは、ドキュメントファイルのスタイルに従うように最善を尽くしてください。 これは、テキストファイルの幅が79文字のソフト制限と、セミフォーマルでありながら親しみやすく親しみやすい散文スタイルを意味します。
Pythonコードを表示するときは、一重引用符で囲まれた文字列を使用します("hello"
の代わりに'hello'
)。
バグレポート
バグレポートは非常に重要です! ただし、問題を提起する前に、 GitHubの問題、オープンとクローズの両方をチェックして、バグが以前に報告されていないことを確認してください。 重複するバグレポートは、他の寄稿者の時間の大きな浪費であり、可能な限り避ける必要があります。
機能リクエスト
リクエストは永続的な機能フリーズにあり、BDFLのみが新機能を追加または承認できます。 メンテナは、現時点ではリクエストは機能が完備されたソフトウェアであると信じています。
広く使用されているオープンソースプロジェクトを維持する上で持つべき最も重要なスキルの1つは、耳と心を開いたまま、提案された変更に対して「いいえ」と言う能力を学ぶことです。
機能が不足していると思われる場合は、遠慮なく機能リクエストを送信してください。ただし、機能リクエストが受け入れられない可能性が非常に高いことに注意してください。