Djangoにはじめて貢献するLink to this heading#

はじめにLink to this heading#

小さなものでも、コミュニティへ恩返しすることに興味がありますか？ たとえば、Django に直してほしいバグを見つけたり、ちょっとした機能を追加してほしいと思っているかもしれません。

その願いを叶える一番の方法は Django 自体にコントリビュートすることです。最初はすごく大変なことだと想像するかもしれませんが、あなたを助けてくれるドキュメント、ツール、コミュニティとともに多くの人が通る道でもあります。これからコントリビュートのプロセス全体を順番に詳しく解説していくので、例を通して理解できると思います。

ソースコードの管理Link to this heading#

Django へ貢献を行う上では、Django コミュニティをオープンで誰にでも開かれたものに保つよう心がけてください。 行動規範 をよく読み、それに従ってください。

Git のインストールLink to this heading#

このチュートリアルでは、Djangoの現在の開発バージョンをダウンロードし、変更内容に対応するブランチを作成するために、Git をインストールしておく必要があります。

Git がインストールされているかどうかを確認するために、コマンドラインで git を入力します。もし入っていない場合は、ダウンロード及びインストールするために、 Git's download page を参照してください。

もし Git について詳しく知らない場合は、(インストール後に) コマンドラインから git help と入力するとコマンドの使い方を確認できます。

Django 開発版の複製を取得Link to this heading#

Django へ貢献するためのはじめの一歩は、ソースコードのコピーです。まず、 GitHub で Django をフォーク して、コマンドラインからリポジトリのクローンを作り、 cd コマンドで Django のローカルコピーのディレクトリに移動しましょう。

以下のコマンドで Django のソースコードリポジトリをダウンロードします:

$ git clone https://github.com/YourGitHubName/django.git

...\> git clone https://github.com/YourGitHubName/django.git

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

例えばホームディレクトリ下の .virtualenvs/ にすべての仮想環境を置くことが出来ます。

次のコマンドで、新しい仮想環境を作成します:

$ python3 -m venv ~/.virtualenvs/djangodev

...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev

新しい環境があるパスはコンピュータに保存されました。

最後のステップとして仮想環境を有効化します：

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

もし source コマンドが使えない場合、代わりに . を試してみてください:

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

新しいターミナルウィンドウを開くたびに仮想環境を有効にする必要があります。

その時点で有効な仮想環境の名前がコマンドライン上に表示されます。これによってどの仮想環境を利用しているのかが分かります。仮想環境のもとで pip によるインストールを行うと、表示されている仮想環境内にインストールされます。他の仮想環境やパッケージインストールによるシステムとは区別されます。

先に進んで、以前にクローンしたDjangoのコピーをインストールしてください:

$ python -m pip install -e /path/to/your/local/clone/django/

...\> py -m pip install -e \path\to\your\local\clone\django\

Djangoのインストールされたバージョンは、編集可能モードでインストールすることにより、ローカルコピーを指すようになります。これにより、加えた変更が即座に反映されるため、初めてのコントリビューションを書く際に非常に役立ちます。

最初に Django のテストスイートを実行するLink to this heading#

Django に貢献する際には、コードの変更が Django の他の領域にバグを持ち込まないようにすることが非常に重要です。変更を行った後もDjangoが動作するかどうかを確認する方法の1つは、Djangoのテストスイートを実行することです。すべてのテストに合格していれば、あなたの変更が機能し、Django の他の部分を壊していないことを合理的に確認することができます。 Django のテストスイートを実行したことがない人は、事前に一度実行して出力に慣れておくと良いでしょう。

テストスイートを実行するする前に cd tests コマンドを使って Django の tests/ ディレクトリに移動し、実行することでテストの依存関係をインストールします。

$ python -m pip install -r requirements/py3.txt

...\> py -m pip install -r requirements\py3.txt

もしこのインストールの間にエラーが発生した場合は、システムが Python のうちの 1 つ以上の依存パッケージが見つからない可能性があります。失敗したパッケージのドキュメントを調べるか、発生したエラーメッセージをウェブで検索してください。

これでテストスイートを実行する準備が整いました:

$ ./runtests.py

...\> runtests.py 

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

Django のテストスイートを実行中に、各テストの完了時のステータスを表す一連の文字が表示されます。 E はテストにエラーが発生したことを表し、 F はテストのアサーションが失敗したことを表しています。これらは共にテスト失敗となります。x と s はそれぞれ期待する失敗とスキップを表しています。ドットはテストの成功を表しています。

スキップされたテストは、テストを実行するために必要な外部ライブラリがインストールされていないことが原因です; 依存については Running all the tests を参照し、あなたの変更に関連するテストにする依存ライブラリがインストールしてください (このチュートリアルでは必要ありません)。いくつかのテストは、特定のデータベースバックエンドに固有であり、そのバックエンドでテストされない場合はスキップされます。 SQLite は、デフォルト設定のバックエンドです。別のバックエンドを使用してテストを実行するには、 Using another settings module を参照してください。

テストが終了するとテストが成功したか､失敗したかを知らせるメッセージが表示されます｡まだ Django のコードに変更を加えていなければ､テストは全て パスするはずです ｡もし失敗するかエラーが起こる場合は､これまでの全ステップを適切に実行してください｡ Running the unit tests で､よりテストについて知れます｡

最新の Django の main ブランチは常に安定しているとは限りません。 main バージョンで開発を行う場合、 Django の継続インテグレーションビルド をチェックしてください。これで、テストの失敗があなたのマシンだけのものか､ Django 公式のビルドによるものかが分かります。各ビルドについてのリンクをクリックすれば､ "Configuration Matrix" という、各 Python のバージョン、 DB バックエンドに対応したテストの失敗を閲覧できます｡

取りかかるLink to this heading#

このチュートリアルでは、ケーススタディとして「架空のチケット」を使って作業を進めます。以下はその架空の詳細です。

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

ブランチを作るLink to this heading#

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

ブランチ名は好きな名前で構いません。"ticket_99999" は一例です。新しいブランチ内で行ったすべての変更は、先ほどクローンしたコードのマスターコピーには影響しません。

チケットにテストを書くLink to this heading#

ほとんどの場合、Djangoにコントリビューションが採用されるには、テストを含める必要があります。バグ修正のコントリビューションの場合、後で同じバグがDjangoに再導入されないようにするため、リグレッションテストを作成する必要があります。リグレッションテストは、バグが存在する間は失敗し、修正されたら成功するように記述してください。新機能を含むコントリビューションの場合、その新機能が正しく動作することを確認するためのテストを含める必要があります。この場合も、機能が存在しない場合は失敗し、実装されると成功するようにテストを作成してください。

新しいテストをコードの変更前に書くのは良い方法です。この開発スタイルはテスト駆動開発 test-driven development と呼ばれ、プロジェクト全体や個々の変更に適用できます。テストを書いたら、それを実行して、実際に失敗することを確認します（まだバグを修正していない、または機能を追加していないため）。新しいテストが失敗しない場合は、修正して失敗するようにする必要があります。なぜなら、バグが存在しているかどうかに関係なく成功するリグレッションテストは、そのバグが再発するのを防ぐのにあまり役立たないからです。

ハンズオンでの例題に移りましょう。

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


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

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

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

チケットにコードを書くLink to this heading#

続いては make_toast() 関数を追加します。

django/ フォルダに移動して shortcuts.py ファイルを開きます。最下行に以下を追加します:

def make_toast():
    return "toast"

さて、先ほど書いたテストが成功したことを確認する必要があるので、追加したコードが正しく機能しているかどうかを確認できます。もう一度、Django の tests/ ディレクトリに移動して以下を実行します:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

テストはすべて成功するはずです。失敗した場合は、正しいファイルに対して正しく関数を追加しているかどうかを確認してください。

Django の テストスイートをもう一度走らせるLink to this heading#

変更内容とテストが正しく動作していることを確認したら、Django全体のテストスイートを実行するのがおすすめです。これにより、あなたの変更がDjangoの他の部分にバグを引き起こしていないことを確認できます。テストスイートをすべて成功させることがコードの完全なバグ修正を保証するわけではありませんが、多くのバグや見逃されがちなリグレッションを特定するのに役立ちます。

Django の全てのテストスイートを走らせるには cd で Django の tests/ ディレクトリ移動して実行してください:

$ ./runtests.py

...\> runtests.py 

ドキュメントを書くLink to this heading#

これは新たな機能です。したがってドキュメントを作る必要があります。ファイル docs/topics/http/shortcuts.txt を開いて、このファイルの最終行に以下を加えます。

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

.. function:: make_toast()

.. versionadded:: 2.2

Returns ``'toast'``.

この新機能は将来のリリースとともに、Django 次期バージョンのリリースノートにも含まれます。ファイル docs/releases/ の最新バージョン、このページの執筆時点では 2.2.txt のリリースノートを開き、"Minor Feature" ヘッダの下にノートを追記してください。

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

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

ドキュメントの書き方についてもっと知りたい場合は ドキュメントを書く を参照してください｡ここでは､ versionadded の書き方についてや､ ドキュメントのコピーをローカルでビルドしてみて､ HTML をプレビューする方法などが書かれています｡

変更点を確認するLink to this heading#

次に、ブランチで行った変更を確認します。すべての変更をステージングしてコミットの準備をするには、次のコマンドを実行します:

$ git add --all

...\> git add --all

上により Django のカレントコピー (修正内容を含む) と、チュートリアル冒頭において行っていたチェックアウトリビジョンとの違いが表示されます。

$ git diff --cached

...\> git diff --cached

ページを進めるには上下キーを使います。

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 キーを押してコマンドラインに戻ります。差分が問題なさそうであれば、変更をコミットする準備が整いました。

変更をコミットするLink to this heading#

変更点をコミットするには、次のコマンドを実行します。

$ git commit

...\> git commit

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

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

コミットのプッシュとプルリクエストの作成Link to this heading#

変更をコミットした後、それをGitHubのフォークに送信します（ブランチ名が異なる場合は、"ticket_99999" をその名前に置き換えてください）:

$ git push origin ticket_99999

...\> git push origin ticket_99999

プルリクエストは Django の GitHub ページ から作成できます。"Your recently pushed branches" の下にあなたのブランチが表示されているはずです。その下の "Compare & pull request" ボタンをクリックします。

このチュートリアルでは実行してはいけませんが、次のページで変更のプレビューが表示されたら、「Create pull request」ボタンをクリックします。

次のステップLink to this heading#

おめでとうございます！ これで Django へのプルリクエストの作成方法を学ぶことができました。応用テクニックについて詳しくは Working with Git and GitHub を読んでください。

これで、Django のコードベースを改良する手助けができるようになりました。