小さなものでも、コミュニティへ恩返しすることに興味がありますか？ たとえば、Django に直してほしいバグを見つけたり、ちょっとした機能を追加してほしいと思っているかもしれません。
\nその願いを叶える一番の方法は Django 自体にコントリビュートすることです。最初はすごく大変なことだと想像するかもしれませんが、実際はとても簡単です。これからコントリビュートのプロセス全体を順番に詳しく解説していくので、例を通して理解できると思います。
\nこのチュートリアルは、少なくとも Django が動作に関して基本的な理解があることを想定しています。つまりチュートリアル 初めての Django アプリ を十分に理解していることを想定しています。また、Python 自体もよく理解している必要があります。もしそうでない場合、 `Dive Into Python`__ というガイドがあります。これは Python プログラマーになるための素晴らしい (かつ無料の) オンラインドキュメントです。
\nバージョン管理システムや Trac をよく知らない方でも、このチュートリアルとリンク先から、コントリビュートに必要な情報は十分得られます。しかし、Django に定期的に貢献したい場合は、このツールの詳細を知っておいた方がいいでしょう。
\nこのチュートリアルでは、できるだけ多くの方が使用できるように、可能な限り詳しく説明したいと思います。
\n\n初めて Django にパッチを送る手順までを詳しく解説しています。このチュートリアルを終えると、関連するツールとプロセス両方について基本的な理解が得られます。具体的には次が対象とする範囲です。
\nGit のインストール
Django 開発版の複製をダウンロードする
Django のテストスイートの実行
パッチへのテストを書く
パッチのコードを書く
パッチをテスト
プルリクエストを送る
より多くの情報を得る方法
チュートリアルを終えたら、次は Django への貢献 を参照してください。このドキュメントには、多くの重要な情報が含まれており、Django に定期的に貢献したい方は是非一読してください。あなたの疑問への答えが見つかるはずです。
\n\n\nあなたはコントリビューターとして私たちDjangoコミュニティをオープンかつ包摂的なものでありつづけることを援助できます。私たちの ソースコードの管理 <https://www.djangoproject.com/conduct/> を参照し、フォローして下さい。
\nこのチュートリアルでは、最新の Django 開発版のダウンロードとその変更のパッチファイルを生成するために Git をインストールする必要があります。
\nGit がインストールされているかどうかを確認するために、コマンドラインで git を入力します。もし入っていない場合は、ダウンロード及びインストールするために、 `Git's download page`__ を参照してください。
もし Git について詳しく知らない場合は、(インストール後に) コマンドラインから git help と入力するとコマンドの使い方を確認できます。
Django へ貢献するためのはじめの一歩は、ソースコードのコピーです。まず、 GitHub で Django をフォーク して、コマンドラインからリポジトリのクローンを作り、 cd コマンドで Django のローカルコピーのディレクトリに移動しましょう。
以下のコマンドで Django のソースコードリポジトリをダウンロードします:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nDjango のローカルコピーがあるので、`` pip`` を使ってパッケージをインストールするのと同じようにインストールすることができます。そのための最も便利な方法は、Python に組み込まれている機能である 仮想環境 を使用することです。これにより、相互に干渉しないようにプロジェクトごとにインストールされたパッケージの別々のディレクトリを保つことができます。
\n例えばホームディレクトリ下の``.virtualenvs/`` にすべての仮想環境を置くことが出来ます。
\n実行することによって、新しい仮想環境を作成します：
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\n新しい環境があるパスはコンピュータに保存されました。
\n最後のステップとして仮想環境を有効化します：
\n$ source ~/.virtualenvs/djangodev/bin/activate\nもし source コマンドが使えない場合、代わりに . を試してみてください:
$ . ~/.virtualenvs/djangodev/bin/activate\n仮想環境の有効化は、ターミナルを新しいウィンドウで開く度に行わなければいけません。virtualenvwrapper__はこの作業をより簡単に行うための便利なツールです。
\nその時点で有効な仮想環境の名前がコマンドライン上に表示されます。これによってどの仮想環境を利用しているのかが分かります。仮想環境のもとで pip によるインストールを行うと、表示されている仮想環境内にインストールされます。他の仮想環境やパッケージインストールによるシステムとは区別されます。
先に進んで、以前にクローンしたDjangoのコピーをインストールしてください:
\nLinux / macOS
$ pip install -e /path/to/your/local/clone/django/\nWindows
...\\> pip install -e \\path\\to\\your\\local\\clone\\django\\\nThe installed version of Django is now pointing at your local copy by installing\nin editable mode. You will immediately see any changes you make to it, which is\nof great help when writing your first patch.
\nIt may be helpful to test your local changes with a Django project. First you\nhave to create a new virtual environment, install the previously cloned\nlocal copy of Django in editable mode,\nand create a new Django project outside of your local copy of Django. You will\nimmediately see any changes you make to Django in your new project, which is\nof great help when writing your first patch.
\nDjangoへ貢献する際、あなたが変更を加えたコードがDjangoのほかの領域でバグを起さないことがとても重要です。コードを変更したあとも、Djangoが動作するか確認する方法の１つとして、Djangoのテストスイートを実行することが挙げられます。全てのテストが通ったら、おそらくあなたの加えた変更は動作しており、Djangoのほかの部分を破損していないことも確かです。これまでDjangoのテストスイートを一度も実行したことがない場合は、事前にテストを実行して出力結果を把握しておくことを推奨します。
\nDjango のテストスイートを実行する前に、Djangoの tests/ ディレクトリに cd で移動して、依存関係をインストールしてから実行してください:
Linux / macOS
$ pip install -r requirements/py3.txt\nWindows
...\\> pip install -r requirements\\py3.txt\nもしこのインストールの間にエラーが発生した場合は、システムが Python のうちの 1 つ以上の依存パッケージが見つからない可能性があります。失敗したパッケージのドキュメントを調べるか、発生したエラーメッセージをウェブで検索してください。
\nテストスイートを実効する準備が出来ました。もし GNU/Linux, macOS 等 Unix 系OSを使用している場合、下記のコマンドを実行します:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \n今すぐ座ってリラックスしてください。Django のテストスイート全体には何千ものテストがあり、コンピュータの速度によっては少なくとも数分かかることがあります。
\nDjango のテストスイートを実行中に、各テストの完了時のステータスを表す一連の文字が表示されます。 E はテストにエラーが発生したことを表し、 F はテストのアサーションが失敗したことを表しています。これらは共にテスト失敗となります。x と s はそれぞれ期待する失敗とスキップを表しています。ドットはテストの成功を表しています。
スキップされたテストは、テストを実行するために必要な外部ライブラリがインストールされていないことが原因です; 依存については Running all the tests を参照し、あなたの変更に関連するテストにする依存ライブラリがインストールしてください (このチュートリアルでは必要ありません)。いくつかのテストは、特定のデータベースバックエンドに固有であり、そのバックエンドでテストされない場合はスキップされます。 SQLite は、デフォルト設定のバックエンドです。別のバックエンドを使用してテストを実行するには、 Using another settings module を参照してください。
\nテストが終了するとテストが成功したか､失敗したかを知らせるメッセージが表示されます｡まだ Django のコードに変更を加えていなければ､テストは全て パスするはずです ｡もし失敗するかエラーが起こる場合は､これまでの全ステップを適切に実行してください｡ Running the unit tests で､よりテストについて知れます｡
\n最新の Django の master は常に安定しているとは限りません。 master バージョンで開発を行う場合、 `Django の継続インテグレーションビルド`__ をチェックしてください。これで、テストの失敗があなたのマシンだけのものか､ Django 公式のビルドによるものかが分かります。各ビルドについてのリンクをクリックすれば､ "Configuration Matrix" という、各 Python のバージョン、 DB バックエンドに対応したテストの失敗を閲覧できます｡
\n\nこのチュートリアルでは、ケーススタディとして「架空のチケット」を使って作業を進めます。以下はその架空の詳細です。
\n\nこれよりこの機能と関連するテストを実装します。
\n変更を加える前に、チケット用に新しいブランチを作ります。
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nブランチ名は好きな名前で構いません。"ticket_99999" は一例です。新しいブランチ内で行ったすべての変更は、先ほどクローンしたコードのマスターコピーには影響しません。
\n大抵の場合、 Django にアクセプトされるパッチはテストを含んでいます。バグフィックス修正の場合、リグレッションテストを書くことで、 Django にバグを再混入していないと後に保証できます。リグレッションテストは、バグが存在しているときに落ちるように書き、バグが修正された後にパスするように書かれるべきです。新機能を含むパッチでは、その新機能が正しく動作すると保証するためにテストが必要です。その際も同じように、テストは、新機能がない段階では落ち、実装されたら通るべきです。
\nこれをするには、コードに変更を加える前に先にテストを書くのが良いでしょう。この開発手法は `テスト駆動開発`__ と呼ばれ、プロジェクト全体にも単一のパッチにも適応可能です。テストを書いた後には、テストを走らせて確かに落ちることを確認します (バグ修正や機能の追加はまだしてないので落ちます)。新しいテストが落ちない場合は落ちるよう修正しましょう。ともかく、バグが存在していようとも通るテストは将来バグが再発するのを防ぐのに何の役にもたちません｡
\nハンズオンでの例題に移りましょう。
\nこのチケットを解決するために、これからb``django``モジュールのトップレベルに``make_toast()``という関数を追加します。まずはこの関数を使うためのテストを書いて、関数の出力が正しいことを確認しましょう。
\nDjangoの``tests/shortcuts/``フォルダへ移動して``test_make_toast.py``というファイルを新たに作ります\n。以下のコードを追加してください。
\nfrom django.shortcuts import make_toast\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), 'toast')\nこのテストは``make_toast()``が``toast``を返すかを確認します。
\n\nまだ``django.shortcuts``に変更を加えていないため、テストは失敗します。``shortcuts``フォルダ内の全てのテストを実行して、どうなるか見てみましょう。``cd``でDjangoの``tests/``ディレクトリへと移動してから実行してください。
\nLinux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nテストが正しく実行されれば追加したテストメソッドに対して、こちらのエラーとともに１つテストが失敗しているはずです。
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nテストがすべて通れば､上記した新しいテストを正しいフォルダ､クラスに追加したことを確認してください｡
\n続いては``make_toast()``関数を追加します。
\ndjango/ フォルダに移動して shortcuts.py ファイルを開きます。最下行に以下を追加します:
def make_toast():\n return 'toast'\nさて、先ほど書いたテストが成功したことを確認する必要があるので、追加したコードが正しく機能しているかどうかを確認できます。もう一度、Django の tests/ ディレクトリに移動して以下を実行します:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nテストはすべて成功するはずです。失敗した場合は、正しいファイルに対して正しく関数を追加しているかどうかを確認してください。
\nパッチとテストが正しく動作していることを確認できたら､ Django のテストをすべて走らせて､変更が Django の別の場所にバグを仕込んでいないか確認しましょう｡すべてのテストが通るという事は､追加したコードがバグフリーだと保証します｡大量のバグや手戻りを発見できます｡そうでないとバグを見逃してしまうでしょう｡
\nDjango の全てのテストスイートを走らせるには cd で Django の tests/ ディレクトリ移動して実行してください:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nこれは新たな機能です。したがってドキュメントを作る必要があります。ファイル docs/topics/http/shortcuts.txt を開いて、このファイルの最終行に以下を加えます。
``make_toast()``\n================\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nこの新機能は将来のリリースとともに、Django 次期バージョンのリリースノートにも含まれます。ファイル docs/releases/ の最新バージョン (これを書いてる時点では 2.2.txt) のリリースノートを開き、"Minor Feature" ヘッダの下にノートを追記してください。
:mod:`django.shortcuts`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nドキュメントの書き方についてもっと知りたい場合は Writing documentation を参照してください｡ここでは､ ``versionadded` の書き方についてや､ ドキュメントのコピーをローカルでビルドしてみて､ HTML をプレビューする方法などが書かれています｡
\nパッチに加えた修正をすべて確認することにしましょう。
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\n上により Django のカレントコピー (修正内容を含む) と、チュートリアル冒頭において行っていたチェックアウトリビジョンとの違いが表示されます。
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nページを進めるには上下キーを使います。
\ndiff --git a/django/shortcuts.py b/django/shortcuts.py\nindex 7ab1df0e9d..8dde9e28d9 100644\n--- a/django/shortcuts.py\n+++ b/django/shortcuts.py\n@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):\n\n # Finally, fall back and assume it's a URL\n return to\n+\n+\n+def make_toast():\n+ return 'toast'\ndiff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\n Minor features\n --------------\n\n+:mod:`django.shortcuts`\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\n+\n :mod:`django.contrib.admin`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ndiff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt\nindex 7b3a3a2c00..711bf6bb6d 100644\n--- a/docs/topics/http/shortcuts.txt\n+++ b/docs/topics/http/shortcuts.txt\n@@ -271,3 +271,12 @@ This example is equivalent to::\n my_objects = list(MyModel.objects.filter(published=True))\n if not my_objects:\n raise Http404("No MyModel matches the given query.")\n+\n+``make_toast()``\n+================\n+\n+.. function:: make_toast()\n+\n+.. versionadded:: 2.2\n+\n+Returns ``'toast'``.\ndiff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py\nnew file mode 100644\nindex 0000000000..6f4c627b6e\n--- /dev/null\n+++ b/tests/shortcuts/test_make_toast.py\n@@ -0,0 +1,7 @@\n+from django.shortcuts import make_toast\n+from django.test import SimpleTestCase\n+\n+\n+class MakeToastTests(SimpleTestCase):\n+ def test_make_toast(self):\n+ self.assertEqual(make_toast(), 'toast')\nパッチのプレビューが終わったら q キーを押してコマンドラインに戻ります。パッチに問題がなければ、変更をコミットしましょう。
変更点をコミットするには、次のコマンドを実行します。
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nすると、コミットメッセージを入力するためのテキストエディタが開きます。 コミットメッセージガイドライン に従って、次のようにメッセージを入力します。
\nFixed #99999 -- Added a shortcut function to make toast.\nパッチをコミットしたら、そのコミットを GitHub 上のあなたのフォークに送りましょう (ブランチ名を変えた場合には "ticket_99999" の部分を置き換えてください)。
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nプルリクエストは Django の GitHub ページ から作成できます。"Your recently pushed branches" の下にあなたのブランチが表示されているはずです。その下の "Compare & pull request" ボタンをクリックします。
\nこのチュートリアルでは行ってはいけませんが、次のページにパッチのプレビューが表示されるので、"Create pull request" をクリックすれば、Django プロジェクトに実際にプルリクエストを送ることができます。
\nおめでとうございます！ これで Django へのプルリクエストの作成方法を学ぶことができました。応用テクニックについて詳しくは Working with Git and GitHub を読んでください。
\nこれで、Django のコードベースを改良する手助けができるようになりました。
\nDjango へのパッチを書き始める前に､貢献するために見ておいたほうがいい情報があります:
\nDjango のドキュメントの チケットをクレームして､パッチを送信する を読んでください｡ Trac でのエチケットやチケットをクレームする方法やパッチに適切なコーディングスタイルなど､重要なことを網羅できます｡
Django への初めての貢献者は 初めての貢献者へのドキュメント を読んでください｡Django に初めて協力する人たちへの良いアドバイスがあります｡
貢献について､より多くの情報を知りたいなら､ 貢献についての Django のドキュメント を参照してください｡そこにはたくさん有用な情報がありまし､質問があれば､このドキュメントが1番役に立ちます｡
ドキュメントをたくさん読んだ後は､実際のパッチを書けるのでチケットを探してみましょう｡ "easy picking" タグが付いたチケットを見つけてください｡このチケットは大抵はより簡単なものなので､初めての貢献者には適切でしょう｡ Django への貢献に慣れてきたあとは､難しく､複雑なチケットを書き始めれるでしょう｡
\n今すぐ始めたいなら (責める人はいません！)、 `パッチが必要な簡単なチケット`__ か `パッチに改善が必要な簡単なチケット`__ を見つけましょう。テストを書きなれているなら `テストが必要な簡単なチケット`__ でもよいでしょう。ただ、チケットのクレームに関するガイドラインに従ってください。 Django ドキュメントの チケットをクレームしてパッチを送る で記述されています。
\nチケットに対してパッチを作ったら、他の人によるレビューが必要です。プルリクエストを送った後は、チケットのメタデータを "has patch"、"doesn't need tests" などのフラグを付けてアップデートして、他の人にレビューが必要だと分かるようにしてください。プロジェクトへの貢献は、必ずしもパッチを書くことだけではありません。すでに書かれたパッチをレビューのレビューもとても助かります。詳しくは Triaging tickets を見てください。
\n