GitHub 検索 Django REST framework

RESTフレームワークへの貢献

世界は一度に一つずつしか変えることができない。その一つを選ぶのがコツだ。

— ティム・バーナーズ＝リー

Django REST framework に貢献する方法はたくさんあります。私たちはこのプロジェクトをコミュニティ主導にしたいと考えていますので、ぜひご参加いただき、プロジェクトの未来を形作る手助けをお願いします。

注: 現在のライフサイクルにおいて、Django REST framework は基本的に機能が完成していると考えています。Django バージョンの継続的な開発を追跡するプルリクエストは受け入れる可能性がありますが、新しい機能やコードフォーマットの変更は受け入れたくありません。

コミュニティ

REST framework プロジェクトを前進させるために最も重要なことは、可能な限り積極的に関与することです。コードの貢献は、プロジェクトに関与するための主要な方法として過大評価されることがよくありますが、私たちはそうである必要はないと考えています。

REST framework を使用している場合は、その経験について発信してください。REST framework の使用に関するブログ記事を書いたり、特定の JavaScript フレームワークでプロジェクトを構築する方法に関するチュートリアルを公開したりすることを検討できます。初心者の経験は、REST framework のどの部分が理解しにくく、扱いにくいかを評価する上で最適な立場にあるため、特に役立ちます。

コミュニティを進歩させるための他の優れた方法には、ディスカッショングループで質問に答えたり、django-rest-frameworkタグの付いた新しい質問があった場合に通知を受けられるようにStackOverflow でメールアラートを設定したりすることが含まれます。

質問に答えるときは、将来の貢献者が関連するスレッドやチケットをハイパーリンクで辿れるようにし、関連する場合はそれらのアイテムからバックリンクを含めるようにしてください。

行動規範

トーンは丁寧かつプロフェッショナルに保ってください。一部のユーザーにとって、REST framework のメーリングリストまたはチケットトラッカーでのディスカッションは、オープンソースコミュニティとの最初の関与となる場合があります。第一印象は重要なので、誰もが歓迎されていると感じられるようにしましょう。

選択する言葉に注意してください。例として、男性が圧倒的に多い環境では、「Hey guys」で始まる投稿は、意図せずに排他的であると受け取られる可能性があります。そのような状況では、性別ニュートラルな言語を使用する方が簡単で、より包括的です。

Django の行動規範には、コミュニティフォーラムに参加するためのより完全なガイドラインが記載されています。

課題

私たちの貢献プロセスは、一般的にGitHub のディスカッションページから始めるべきということです。ディスカッションの後で推奨された場合にのみ、課題やプルリクエストを提起してください。

潜在的な良い課題報告に関するいくつかのヒント

  • 課題を説明するときは、変更する必要があると思うコードではなく、変更する必要があると思う動作の観点からチケットを表現するようにしてください。
  • GitHub プロジェクトページで関連アイテムを検索し、課題を報告する前に、REST framework の最新バージョンを実行していることを確認してください。
  • 機能リクエストは、コア REST framework ライブラリの外部で実装することを推奨してクローズされることがよくあります。新しい機能リクエストをサードパーティライブラリとして実装することで、REST framework のメンテナンスオーバーヘッドを抑え、安定性、バグ修正、優れたドキュメントに集中できるようになります。現在のライフサイクルにおいて、Django REST framework は基本的に機能が完成していると考えています。
  • 課題をクローズしても、必ずしもディスカッションが終了するわけではありません。課題が誤ってクローズされたと思われる場合は、その理由を説明してください。再開する必要があるかどうかを検討します。

課題のトリアージ

着信課題のトリアージに参加することは、貢献を始めるための良い方法です。チケットトラッカーに入るすべてのチケットを、次のステップを決定するために確認する必要があります。誰でもこれに協力できます。必要なのは、次のことを行う意思だけです。

  • チケットを読み通す - 意味が通じますか？より良く説明するために役立つコンテキストが不足していませんか？
  • チケットは正しい場所に報告されていますか？ディスカッショングループでのディスカッションとしてより適切ではありませんか？
  • チケットがバグレポートの場合、それを再現できますか？問題を示す失敗するテストケースを作成し、プルリクエストとして提出できますか？
  • チケットが機能リクエストの場合、それに同意しますか？また、機能リクエストをサードパーティパッケージとして実装することはできますか？
  • チケットがあまり活動がなく、必要なものに対応している場合は、チケットにコメントして、再び動かすために何が必要かを確認してください。

開発

Django REST framework の開発を開始するには、まず GitHub のDjango REST Framework リポジトリからフォークを作成します。

次に、フォークをクローンします。クローンコマンドは次のようになります。YOUR-USERNAME の代わりに GitHub ユーザー名を使用します。

git clone https://github.com/YOUR-USERNAME/django-rest-framework

詳細については、GitHub の リポジトリのフォークガイドを参照してください。

変更は、概ねPEP 8 スタイル規則に従う必要があり、非準拠スタイルを自動的に示すようにエディターを設定することをお勧めします。コミットするたびに pre-commit フックを使用して、これらの規則に対して貢献を確認できます。これは CI でも実行されます。設定するには、まず pre-commit ツールがインストールされていることを確認します。例:

python -m pip install pre-commit

次に、実行します

pre-commit install

テスト

テストを実行するには、リポジトリをクローンし、次に

# Setup the virtual environment
python3 -m venv env
source env/bin/activate
pip install -e .
pip install -r requirements.txt

# Run the tests
./runtests.py

テストオプション

より簡潔な出力スタイルを使用して実行します。

./runtests.py -q

特定のテストケースのテストを実行します。

./runtests.py MyTestCase

特定のテストメソッドのテストを実行します。

./runtests.py MyTestCase.test_this_method

特定のテストメソッドのテストを実行するための短い形式。

./runtests.py test_this_method

注: テストケースとテストメソッドのマッチングは曖昧で、指定されたコマンドライン入力に部分的に一致する文字列を含む他のテストを実行する場合があります。

複数の環境に対して実行する

優れた tox テストツールを使用して、サポートされているすべての Python および Django バージョンに対してテストを実行することもできます。tox をグローバルにインストールし、次に

tox

プルリクエスト

早い段階でプルリクエストを作成することをお勧めします。プルリクエストはディスカッションの開始を表しており、必ずしも最終的な完成した提出物である必要はありません。

プルリクエストの作業を開始する前に、常に新しいブランチを作成するのが最適です。つまり、進行中のプルリクエストを妨害することなく、別の別の課題に取り組むために後で切り替えることができるようになります。

また、未処理のプルリクエストがある場合、GitHub リポジトリに新しいコミットをプッシュすると、プルリクエストも自動的に更新されることを覚えておくと便利です。

プルリクエストの操作に関する GitHub のドキュメントは、こちらで入手できます。

プルリクエストを送信する前に必ずテストを実行し、理想的には tox を実行して、変更がサポートされているすべてのバージョンの Python および Django で互換性があることを確認してください。

プルリクエストを作成したら、GitHub インターフェースでビルドステータスを確認し、テストが期待どおりに実行されていることを確認してください。

Build status

上記: ビルド通知

互換性の問題の管理

場合によっては、コードが Django、Python、またはサードパーティライブラリのさまざまなバージョンで動作するようにするために、環境に応じてわずかに異なるコードを実行する必要があります。このように分岐するコードはすべて compat.py モジュールに分離し、コードベースの残りの部分が使用できる単一の共通インターフェースを提供する必要があります。

ドキュメント

REST framework のドキュメントは、docs ディレクトリにある Markdown ソースファイルから作成されます。

ドキュメントの操作を非常に簡単にする優れた Markdown エディターが多数あります。Mac 用の Mou エディターは、特にお勧めのエディターです。

ドキュメントのビルド

ドキュメントをビルドするには、pip install mkdocs で MkDocs をインストールし、次のコマンドを実行します。

mkdocs build

これにより、ドキュメントは site ディレクトリに構築されます。

serve コマンドを使用すると、ドキュメントを構築してブラウザウィンドウでプレビューを開くことができます。

mkdocs serve

言語スタイル

ドキュメントはアメリカ英語で記述する必要があります。ドキュメントのトーンは非常に重要です。可能な限り、シンプルで、平易、客観的、そしてバランスの取れたスタイルを心がけてください。

その他のヒント

  • 段落は適度に短くしてください。
  • 'e.g.' のような略語は使用せず、代わりに 'For example' のように完全な形を使用してください。

Markdownスタイル

ドキュメントを作成する際には、従うべきいくつかの規則があります。

1. ヘッダー

ヘッダーにはハッシュスタイルを使用してください。例えば

### Some important topic

アンダースタイルは使用しないでください。これはしないでください:

Some important topic
====================

リンクは常に参照スタイルを使用し、参照されるハイパーリンクはドキュメントの最後にまとめてください。

Here is a link to [some other thing][other-thing].

More text...

[other-thing]: http://example.com/other/thing

このスタイルは、ドキュメントのソースの一貫性と可読性を維持するのに役立ちます。

別のRESTフレームワークのドキュメントにハイパーリンクする場合は、相対リンクを使用し、.md サフィックスにリンクする必要があります。例えば

[authentication]: ../api-guide/authentication.md

このスタイルのリンクは、Markdownエディターでハイパーリンクをクリックして、参照先のドキュメントを開くことができることを意味します。ドキュメントが構築されると、これらのリンクはHTMLページへの通常のリンクに変換されます。

3. 注記

注記や警告に注意を引かせたい場合は、以下のように、囲み線を一組使用してください。

---

**Note:** A useful documentation note.

---