Djangoの最初のパッチを書く

序章

コミュニティに少し還元することに興味がありますか？おそらく、修正したいDjangoのバグを見つけたか、追加したい小さな機能があるかもしれません。

Django自体に貢献することは、自分の懸念に対処するための最良の方法です。これは最初は気が遠くなるように思えるかもしれませんが、ドキュメント、ツール、およびあなたをサポートするコミュニティを備えた、よく旅された道です。プロセス全体を順を追って説明するので、例を挙げて学ぶことができます。

このチュートリアルは誰のためのものですか？

も参照してください

コードの貢献の詳細に関するリファレンスを探している場合は、コードの記述[X104X]のドキュメントを参照してください。

このチュートリアルでは、Djangoがどのように機能するかについて少なくとも基本的な知識があることを前提としています。これは、最初のDjangoアプリの作成に関する既存のチュートリアルを快適に実行できることを意味します。さらに、Python自体をよく理解している必要があります。しかし、そうでない場合は、 Dive Into Python は、Pythonプログラマーを始めるための素晴らしい（そして無料の）オンラインブックです。

バージョン管理システムとTracに慣れていない方は、このチュートリアルとそのリンクに、開始するのに十分な情報が含まれていることに気付くでしょう。ただし、Djangoに定期的に貢献する予定がある場合は、これらのさまざまなツールについてもう少し読みたいと思うでしょう。

ただし、ほとんどの場合、このチュートリアルでは、できるだけ多くの人に役立つように、できるだけ多くのことを説明しようとしています。

助けを得る場所：

このチュートリアルの実行に問題がある場合は、 django-developers にメッセージを投稿するか、irc.libera.chat の＃django-devに立ち寄って他のDjangoユーザーとチャットしてください。誰が助けることができるかもしれません。

このチュートリアルは何をカバーしていますか？

初めてDjangoにパッチを提供する方法を説明します。このチュートリアルを終了するまでに、関連するツールとプロセスの両方の基本を理解しているはずです。具体的には、以下について説明します。

Gitのインストール。
Djangoの開発バージョンのコピーをダウンロードします。
Djangoのテストスイートを実行しています。
パッチのテストを作成します。
パッチのコードを書く。
パッチをテストします。
プルリクエストを送信します。
詳細情報を探す場所。

チュートリアルが終了したら、 Djangoの貢献に関するドキュメントの残りの部分を確認できます。すばらしい情報がたくさん含まれており、Djangoの定期的な寄稿者になりたい人は必読です。質問がある場合は、おそらく答えがあります。

Python 3が必要です！

Djangoの現在のバージョンはPython2.7をサポートしていません。 PythonのダウンロードページまたはオペレーティングシステムのパッケージマネージャーでPython3を入手してください。

Windowsユーザーの場合

追加のガイダンスについては、Windowsドキュメントの Install Python を参照してください。

行動規範

貢献者として、Djangoコミュニティをオープンで包括的なものに保つのを手伝ってください。行動規範を読み、それに従ってください。

Gitのインストール

このチュートリアルでは、Gitをインストールして、Djangoの現在の開発バージョンをダウンロードし、加えた変更のパッチファイルを生成する必要があります。

Gitがインストールされているかどうかを確認するには、コマンドラインにgitと入力します。このコマンドが見つからないというメッセージが表示された場合は、ダウンロードしてインストールする必要があります。 Gitのダウンロードページを参照してください。

Gitにあまり詳しくない場合は、コマンドラインにgit helpと入力することで、Gitのコマンド（インストール後）についていつでも詳しく知ることができます。

Djangoの開発バージョンのコピーを取得する

Djangoに貢献するための最初のステップは、ソースコードのコピーを入手することです。まず、 GitHub でDjangoをフォークします。次に、コマンドラインからcdコマンドを使用して、Djangoのローカルコピーを配置するディレクトリに移動します。

次のコマンドを使用して、Djangoソースコードリポジトリをダウンロードします。

低帯域幅接続？

--depth 1引数をgit cloneに追加すると、Djangoのすべてのコミット履歴のダウンロードをスキップできます。これにより、データ転送が約250MBから約70MBに削減されます。

Djangoのローカルコピーができたので、pipを使用して他のパッケージをインストールするのと同じようにインストールできます。これを行う最も便利な方法は、仮想環境を使用することです。これは、Pythonに組み込まれている機能であり、プロジェクトごとにインストール済みパッケージの個別のディレクトリを保持して、干渉しないようにすることができます。お互いに。

すべての仮想環境を1つの場所、たとえばホームディレクトリの.virtualenvs/に保持することをお勧めします。

次のコマンドを実行して、新しい仮想環境を作成します。

パスは、新しい環境がコンピューターに保存される場所です。

仮想環境をセットアップする最後のステップは、仮想環境をアクティブ化することです。

$ source ~/.virtualenvs/djangodev/bin/activate

sourceコマンドが使用できない場合は、代わりにドットを使用してみてください。

$ . ~/.virtualenvs/djangodev/bin/activate

新しいターミナルウィンドウを開くたびに、仮想環境をアクティブ化する必要があります。

Windowsユーザーの場合

Windowsで仮想環境をアクティブ化するには、次のコマンドを実行します。

...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

現在アクティブ化されている仮想環境の名前がコマンドラインに表示され、使用している仮想環境を追跡するのに役立ちます。この名前が表示されているときにpipを介してインストールしたものはすべて、その仮想環境にインストールされ、他の環境やシステム全体のパッケージから分離されます。

先に進み、以前にクローン化されたDjangoのコピーをインストールします。

インストールされたバージョンのDjangoは、編集可能モードでインストールすることにより、ローカルコピーを指しているようになりました。加えた変更がすぐに表示されます。これは、最初のパッチを作成するときに非常に役立ちます。

Djangoのローカルコピーを使用してプロジェクトを作成する

Djangoプロジェクトでローカルの変更をテストすると役立つ場合があります。まず、新しい仮想環境を作成し、以前に複製したDjangoのローカルコピーを編集可能モードでインストールし、Djangoのローカルコピーの外部に新しいDjangoプロジェクトを作成する必要があります。新しいプロジェクトでDjangoに加えた変更がすぐに表示されます。これは、最初のパッチを作成するときに非常に役立ちます。

Djangoのテストスイートを初めて実行する

Djangoに貢献するときは、コードの変更によってDjangoの他の領域にバグが発生しないことが非常に重要です。変更を加えた後もDjangoが機能することを確認する1つの方法は、Djangoのテストスイートを実行することです。それでもすべてのテストに合格する場合は、変更が機能し、Djangoの他の部分が壊れていないことを合理的に確信できます。これまでDjangoのテストスイートを実行したことがない場合は、出力に慣れるために、事前に1回実行することをお勧めします。

テストスイートを実行する前に、cd -ingを使用して依存関係をDjango tests/ディレクトリにインストールし、次のコマンドを実行します。

インストール中にエラーが発生した場合は、システムに1つ以上のPythonパッケージの依存関係がない可能性があります。失敗したパッケージのドキュメントを参照するか、発生したエラーメッセージを使用してWebを検索してください。

これで、テストスイートを実行する準備が整いました。 GNU / Linux、macOS、またはその他の種類のUnixを使用している場合は、次のコマンドを実行します。

さあ、座ってリラックスしましょう。 Djangoのテストスイート全体には数千のテストがあり、コンピューターの速度にもよりますが、実行には少なくとも数分かかります。

Djangoのテストスイートの実行中は、各テストの完了時のステータスを表す文字のストリームが表示されます。 Eはテスト中にエラーが発生したことを示し、Fはテストのアサーションが失敗したことを示します。これらは両方ともテストの失敗と見なされます。一方、xとsは、それぞれ予想される障害とスキップされたテストを示していました。ドットはテストに合格したことを示します。

スキップされたテストは通常、テストの実行に必要な外部ライブラリが欠落していることが原因です。依存関係のリストについては、すべてのテストの実行を参照してください。また、行っている変更に関連するテストについては、必ずインストールしてください（このチュートリアルでは必要ありません）。一部のテストは特定のデータベースバックエンドに固有であり、そのバックエンドでテストしない場合はスキップされます。 SQLiteは、デフォルト設定のデータベースバックエンドです。別のバックエンドを使用してテストを実行するには、別の設定モジュールの使用を参照してください。

テストが完了すると、テストスイートが合格したか失敗したかを通知するメッセージが表示されます。 Djangoのコードにはまだ変更を加えていないため、テストスイート全体はに合格する必要があります。失敗またはエラーが発生した場合は、前のすべての手順を正しく実行したことを確認してください。詳細については、単体テストの実行を参照してください。

最新のDjangoの「メイン」ブランチは常に安定しているとは限らないことに注意してください。「メイン」に対して開発する場合、 Djangoの継続的インテグレーションビルドをチェックして、障害がマシンに固有のものであるか、またはDjangoの公式ビルドにも存在するかどうかを判断できます。クリックして特定のビルドを表示すると、Pythonのバージョンとデータベースバックエンドごとに分類された障害を示す「構成マトリックス」を表示できます。

ノート

このチュートリアルと現在取り組んでいるチケットでは、SQLiteに対するテストで十分ですが、別のデータベースを使用してテストを実行することは可能です（場合によっては必要です）。

機能に取り組んでいます

このチュートリアルでは、ケーススタディとして「偽のチケット」に取り組みます。架空の詳細は次のとおりです。

チケット＃99999 –トーストを作ることを許可する

Djangoは、'toast'を返す関数django.shortcuts.make_toast()を提供する必要があります。

この機能と関連するテストを実装します。

パッチのブランチを作成する

変更を加える前に、チケットの新しいブランチを作成します。

ブランチには任意の名前を選択できます。例として「ticket_99999」があります。このブランチで行われたすべての変更はチケットに固有であり、以前に複製したコードのメインコピーには影響しません。

チケットのテストを書く

ほとんどの場合、パッチをDjangoに受け入れるには、テストを含める必要があります。バグ修正パッチの場合、これは、バグが後でDjangoに再導入されないことを確認するための回帰テストを作成することを意味します。回帰テストは、バグがまだ存在している間は失敗し、バグが修正されると合格するように作成する必要があります。新機能を含むパッチの場合、新機能が正しく機能していることを確認するテストを含める必要があります。新しい機能が存在しない場合は失敗し、実装されると合格するはずです。

これを行う良い方法は、コードに変更を加える前に、最初に新しいテストを作成することです。このスタイルの開発はテスト駆動開発と呼ばれ、プロジェクト全体と単一のパッチの両方に適用できます。テストを作成したら、テストを実行して、実際に失敗することを確認します（バグを修正していないか、その機能をまだ追加していないため）。新しいテストが失敗しない場合は、失敗するように修正する必要があります。結局のところ、バグが存在するかどうかに関係なく合格する回帰テストは、そのバグが将来再発するのを防ぐのにあまり役立ちません。

次に、実践的な例を示します。

チケット＃99999のテストを書く

このチケットを解決するために、make_toast()関数をトップレベルのdjangoモジュールに追加します。まず、関数を使用してその出力が正しいことを確認するテストを作成します。

Djangoのtests/shortcuts/フォルダーに移動し、新しいファイルtest_make_toast.pyを作成します。次のコードを追加します。

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), 'toast')

このテストは、make_toast()が'toast'を返すことを確認します。

しかし、このテストはちょっと難しいようです…

これまでテストを扱う必要がなかった場合、一見するとテストを書くのが少し難しいように見えることがあります。幸いなことに、テストはコンピュータープログラミングの非常に大きな主題であるため、そこには多くの情報があります。

Djangoのテストの作成に関する最初の良い見方は、テストの作成と実行のドキュメントにあります。
Dive Into Python（Python開発者向けの無料のオンラインブック）には、ユニットテストの概要が含まれています。
それらを読んだ後、少し肉付きの良いものに歯を食い込ませたい場合は、常にPython unittestのドキュメントがあります。

新しいテストの実行

django.shortcutsにはまだ変更を加えていないため、テストは失敗するはずです。 shortcutsフォルダー内のすべてのテストを実行して、それが実際に行われていることを確認しましょう。 cdをDjango tests/ディレクトリに移動し、次のコマンドを実行します。

テストが正しく実行された場合、追加したテスト方法に対応する1つの失敗が表示され、次のエラーが発生します。

ImportError: cannot import name 'make_toast' from 'django.shortcuts'

すべてのテストに合格した場合は、上記の新しいテストを適切なフォルダーとファイル名に追加したことを確認する必要があります。

チケットのコードを書く

次に、make_toast()関数を追加します。

django/フォルダーに移動し、shortcuts.pyファイルを開きます。下部に、以下を追加します。

def make_toast():
    return 'toast'

ここで、前に作成したテストに合格することを確認する必要があります。これにより、追加したコードが正しく機能しているかどうかを確認できます。ここでも、Django tests/ディレクトリに移動して、次のコマンドを実行します。

すべてが合格するはずです。そうでない場合は、関数を正しいファイルに正しく追加したことを確認してください。

Djangoのテストスイートを2回実行する

パッチとテストが正しく機能していることを確認したら、Djangoテストスイート全体を実行して、変更によってDjangoの他の領域にバグが発生していないことを確認することをお勧めします。テストスイート全体に合格しても、コードにバグがないことは保証されませんが、他の方法では見過ごされがちな多くのバグやリグレッションを特定するのに役立ちます。

Djangoテストスイート全体を実行するには、cdをDjango tests/ディレクトリに移動し、次のコマンドを実行します。

ドキュメントの作成

これは新機能であるため、文書化する必要があります。ファイルdocs/topics/http/shortcuts.txtを開き、ファイルの最後に以下を追加します。

``make_toast()``
================

.. function:: make_toast()

.. versionadded:: 2.2

Returns ``'toast'``.

この新機能は今後のリリースで提供されるため、Djangoの次のバージョンのリリースノートにも追加されます。最新バージョンのリリースノートをdocs/releases/で開きます。これは、執筆時点では2.2.txtです。「マイナー機能」ヘッダーの下にメモを追加します。

:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~

* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

versionaddedビットの説明など、ドキュメントの作成の詳細については、ドキュメントの作成を参照してください。このページには、ドキュメントのコピーをローカルで作成する方法の説明も含まれているため、生成されるHTMLをプレビューできます。

変更のプレビュー

次に、パッチで行われたすべての変更を確認します。コミットの準備ができているすべての変更をステージングするには、次のコマンドを実行します。

次に、Djangoの現在のコピー（変更を加えたもの）と、チュートリアルの前半で最初にチェックアウトしたリビジョンとの違いを次のように表示します。

矢印キーを使用して上下に移動します。

diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):

     # Finally, fall back and assume it's a URL
     return to
+
+
+def make_toast():
+    return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
 Minor features
 --------------

+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
 :mod:`django.contrib.admin`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
         my_objects = list(MyModel.objects.filter(published=True))
         if not my_objects:
             raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+    def test_make_toast(self):
+        self.assertEqual(make_toast(), 'toast')

パッチのプレビューが終了したら、qキーを押してコマンドラインに戻ります。パッチの内容に問題がないように見えたら、変更をコミットします。

パッチの変更をコミットする

変更をコミットするには：

これにより、コミットメッセージを入力するためのテキストエディタが開きます。コミットメッセージガイドラインに従い、次のようなメッセージを記述します。

Fixed #99999 -- Added a shortcut function to make toast.

コミットをプッシュしてプルリクエストを行う

パッチをコミットした後、GitHubのフォークに送信します（ブランチの名前が異なる場合は、「ticket_99999」をブランチの名前に置き換えます）。

Django GitHubページにアクセスして、プルリクエストを作成できます。「最近プッシュされたブランチ」の下にブランチが表示されます。その横にある「比較とプルリクエスト」をクリックします。

このチュートリアルでは実行しないでください。ただし、パッチのプレビューが表示される次のページで、[プルリクエストの作成]をクリックします。

次のステップ

おめでとうございます。Djangoにプルリクエストを送信する方法を学びました。必要になる可能性のあるより高度なテクニックの詳細は、 GitおよびGitHubの操作にあります。

これで、Djangoのコードベースの改善を支援することで、これらのスキルを有効に活用できます。

新しい寄稿者のための詳細情報

Djangoのパッチの作成に取り掛かる前に、貢献に関するもう少し情報がありますので、おそらく確認する必要があります。

チケットの請求とパッチの送信に関するDjangoのドキュメントを必ずお読みください。 Tracのエチケット、自分でチケットを請求する方法、パッチの予想されるコーディングスタイル、およびその他の多くの重要な詳細について説明します。
初めての寄稿者は、Djangoの初めての寄稿者のドキュメントも読む必要があります。 Djangoを手伝うのが初めての私たちにとっては良いアドバイスがたくさんあります。
その後、貢献についての詳細がまだ必要な場合は、 Djangoの貢献に関するドキュメントの残りの部分をいつでも参照できます。それはたくさんの有用な情報を含んでいて、あなたが持っているかもしれないどんな質問にでも答えるためのあなたの最初の情報源であるべきです。

あなたの最初の本当のチケットを見つける

その情報のいくつかを調べたら、外に出てパッチを書くための自分のチケットを見つける準備ができています。「簡単なピッキング」基準のチケットには特に注意してください。これらのチケットは、多くの場合、本質的にはるかに単純であり、初めての寄稿者に最適です。 Djangoへの貢献に慣れたら、より困難で複雑なチケットのパッチの作成に進むことができます。

すでに始めたいだけの場合（そして誰もあなたを責めないでしょう！）、パッチが必要な簡単なチケットと改善が必要なパッチがある簡単なチケットのリストを見てみてください。 X209X]。テストの作成に精通している場合は、テストが必要な簡単なチケットのリストも確認できます。チケットの請求とパッチの送信に関するDjangoのドキュメントへのリンクに記載されているチケットの請求に関するガイドラインに従うことを忘れないでください。

プルリクエストを作成した後の次は何ですか？

チケットにパッチが適用されたら、2番目の目で確認する必要があります。プルリクエストを送信した後、チケットのフラグを「パッチあり」、「テスト不要」などに設定してチケットメタデータを更新し、他の人がレビューできるようにします。貢献することは、必ずしも最初からパッチを書くことを意味するわけではありません。既存のパッチを確認することも非常に役立ちます。詳細については、トリアージチケットを参照してください。

Djangoの最初のパッチを書く—Djangoドキュメント

目次