少しでもコミュニティへ恩返しをしたいと思われますか? それは 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 への貢献の第一歩はソースコードの複製の取得から始まります。コマンドラインで、 cd コマンドを使い、Django をローカルに複製するディレクトリに移動します。
以下のコマンドで Django のソースコードリポジトリをダウンロードします:
\n$ git clone https://github.com/django/django.git\n今やあなたはDjangoのローカルコピーを手に入れました、"pip"を使ってどんなパッケージでもインストールできるのと同じように、Djangoもインストールできます。Pythonに含まれる機能である virtual environment (もしくはvirtualenv)は、プロジェクトごとにインストールされたパッケージが互いに害を及ぼすことないよう、別々のディレクトリで維持することを可能にする、もっとも便利な方法です。
\nホームディレクトリの .virtualenvs/ 以下に、すべてのvirtualenvを 1 箇所においておくといいです。もしまだそのフォルダが存在しないなら作成しましょう。
$ mkdir ~/.virtualenvs\nそれではアプリケーションを実行するために新しいvirtualenvを作りましょう:
\n$ python3 -m venv ~/.virtualenvs/djangodev\n新しい環境があるパスはコンピュータに保存されました。
\n\n\nvirtualenvを有効化すれば設定は終わりです:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nもし source コマンドが使えない場合、代わりに . を試してみてください:
$ . ~/.virtualenvs/djangodev/bin/activate\nターミナルの新しいウィンドウを開いたときは、virtualenvを有効にする必要があります。 virtualenvwrapper はこれをより簡単にできるツールです。
\nこれより pip を通じてインストールした何もかもが、他の環境やシステムワイドなパッケージから分離されて、新しいvirtualenvにインストールされます。また、どの環境を使っているのかがわかるように現在有効なvirtualenvの名前がコマンドラインに表示されます。先ほどクローンしたDjangoのコピーをインストールして作業を続行します:
$ pip install -e /path/to/your/local/clone/django/\n現在インストールされたDjangoはあなたのローカルコピーを参照しています。あなたが行ったどのような変更も迅速に確認できます、これはあなたが最初のパッチを作成するときの大きな助けになります。
\nこのチュートリアルでは、ケーススタディとして #24788 を用います。そのために、まず Django のバージョンをパッチが適用される前の git のバージョンに戻します。これによりスクラッチからパッチの作成、 Django のテストスイートの実行を含む全ての手順を解説します。
\nチュートリアルでは trunk ではない古いリビジョンの Django を使用しますが、自分のパッチを作成する場合は Django の最新の開発版を使用する必要があります!
\n\nDjango のルートディレクトリ (このディレクトリには django, docs, tests, AUTHORS, 等が含まれています) へ移動します。次にチュートリアルで使用する Django の旧リビジョンをチェックアウトします。
$ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887\nDjango へ貢献する際、変更したコードが Django の他の領域にバグを混入しないことが非常に重要です。変更後に Django の正常動作を確認するには Django のテストスイートを実行します。すべてのテストに合格した場合は、その変更により Django が壊れていないことが確認できます。Django のテストスイートを実行したことが一度もない場合、その出力結果を把握しておくために一度テストスイートを実行しておくことを推奨します。
\nDjango のテストスイートを走らせる前に、まずは Djangoの tests/ ディレクトリに cd で移動して、依存関係をインストールしてください:
$ pip install -r requirements/py3.txt\nテストスイートを実効する準備が出来ました。もし GNU/Linux, Mac OS X 等 Unix 系OSを使用している場合、下記のコマンドを実行します:
\n$ ./runtests.py\nそれでは一息つきましょう。Django 全体のテストスイートは 9600 以上のテストが含まれており、コンピュータの速度により 5 〜 15分程度かかります。
\nDjango のテストスイートを実行中に、各テストの状態を文字のストリームで確認することができます。 E はテストにエラーが発生したことを表し、 F はテストのアサーションが失敗したことを表しています。これらは共にテスト失敗となります。x と s はそれぞれ期待する失敗とスキップを表しています。ドットはテストの成功を表しています。
スキップされたテストは、テストを実行するために必要な外部ライブラリがインストールされていないことが原因です; 依存については Running all the tests を参照し、関連するテストを実行してください (このチュートリアルでは必要ありません)。
\nOnce the tests complete, you should be greeted with a message informing you\nwhether the test suite passed or failed. Since you haven't yet made any changes\nto Django's code, the entire test suite should pass. If you get failures or\nerrors make sure you've followed all of the previous steps properly. See\nRunning the unit tests for more information. If you're using Python 3.5+,\nthere will be a couple failures related to deprecation warnings that you can\nignore. These failures have since been fixed in Django.
\n開発中の､最新の Django ではステーブルとは限りません｡トランクバージョンで開発を行う場合､ Django の継続インテグレーションビルド をチェックしてください｡これで､テストの失敗があなたのマシンだけのものか､ Django 公式のビルドによるものかが分かります｡各ビルドについてのリンクをクリックすれば､ "Configuration Matrix" という､ 各 Python のバージョン､ DB バックエンドに対応したテストの失敗を閲覧できます｡
\n\n大抵の場合､ Django にアクセプトされるパッチはテストを含んでいます｡リグレッションテストを書くことで､ Django にバグを再混入していないと後に保証できます｡レグレッションテストは､バグが存在しているときに落ちるように書き､バグが修正された後にパスするように書かれるべきです｡新機能を含むパッチでは､その新機能が正しく動作すると保証するためにテストが必要です｡その際も同じように､新機能が無い際には落ち､実装されてから通るテストを書くべきです｡
\nこれをするには､コードに変更を加える前に先にテストを書くのが良いでしょう｡この開発手法は テスト駆動開発 と呼ばれ､プロジェクト全体にも単一のパッチにも適応可能です｡テストを書いた後には､テストを走らせて確かに落ちることを確認します (バグ修正や昨日の追加はまだしてないので落ちます)｡ 新しいテストが落ちない場合は落ちるよう修正しましょう｡ともかく､バグが存在していようとも通るテストは将来バグが再発するのを防ぐのに､何の役にもたちません｡
\nハンズオンでの例題
\nチケット #24788 は、Formクラスにおいてクラスレベルの属性 prefix を指定可能にするという小さな機能追加を、このように提案しています:
[…] forms which ship with apps could effectively namespace themselves such\nthat N overlapping form fields could be POSTed at once and resolved to the\ncorrect form.\nこのチケットを解決するには､ prefix 属性を BaseForm に追加します｡このクラスのインスタンスを作成する時、 __init__() メソッドに prefix を渡すと、作成されたインスタンスに prefix がセットされます。 しかし prefix を渡さない(または None を与える)場合、クラスレベルのprefixが使用されます。変更を加える前に､変更が正しく動作し､これからも動作し続けることを確認するためにテストをいくつか追加します｡
Django の tests/forms_tests/tests/ フォルダに移動して tests_forms.py ファイルを開きます。以下のコードを ``test_forms_with_null_boolean `` 関数の直前の 1674 行目に追加します:
def test_class_prefix(self):\n # Prefix can be also specified at the class level.\n class Person(Form):\n first_name = CharField()\n prefix = 'foo'\n\n p = Person()\n self.assertEqual(p.prefix, 'foo')\n\n p = Person(prefix='bar')\n self.assertEqual(p.prefix, 'bar')\nこの新しいテストは、 クラスレベルの prefix が期待通りに設定されていることと、インスタンスの生成時にまだ prefix パラメータが渡されていることを確認します。
BaseForm `` にはまだ変更を加えていませんので､テストは落ちます｡ ``forms_tests `` フォルダの全テストを走らせて､実際に何が起こるか観てみましょう｡コマンドラインで ``tests/ ディレクトリに cd して､以下を実行してください:
$ ./runtests.py forms_tests\nテストが正しく実行されれば､追加したテストメソッドに対応する1つのテストが失敗するでしょう｡テストがすべて通れば､上記した新しいテストを正しいフォルダ､クラスに追加したことを確認してください｡
\n次は :ticket:`24788 ` で説明されている機能を Django に追加します｡
\ndjango/django/contrib/forms フォルダーに行って､ forms.py ファイルを開いてください｡\n72行目にある BaseForm クラスを見つけて､以下の prefix クラス属性をすでにある field_order 属性の下に追加してください:
class BaseForm(object):\n # This is the main implementation of all the Form logic. Note that this\n # class is different than Form. See the comments by the Form class for\n # more information. Any improvements to the form API should be made to\n # *this* class, not to the Form class.\n field_order = None\n prefix = None\nDjango への変更が完了したあと､コードが正しく動作すると確認するため､先ほど書いたテストを実行してください｡Djangoの form_tests フォルダーに cd で移動して､以下を実行してください:
$ ./runtests.py forms_tests\nあぁ､テストを書いていて良かったですね｡以下のように1つテストが落ちています:
\nAssertionError: None != 'foo'\n__init__``メソッドの中に条件文を追加するのを忘れていました。``django/forms/forms.py の87行目の``self.prefix = prefix``を参照して変更します。条件文を追加しましょう:
if prefix is not None:\n self.prefix = prefix\n再実行すればテストがすべてパスするはずです｡もしそうでない場合､ BaseForm クラスと新しいテストが正しくコピーされているされていると確認してください｡
パッチとテストが正しく動作していることを確認できたら､ Django のテストをすべて走らせて､変更が Django の別の場所にバグを仕込んでいないか確認しましょう｡すべてのテストが通るという事は､追加したコードがバグフリーだと保証します｡大量のバグや手戻りを発見できます｡そうでないとバグを見逃してしまうでしょう｡
\nDjango の全てのテストスイートを走らせるには cd で Django の tests/ ディレクトリ移動して実行してください:
$ ./runtests.py\nどのテストも失敗していない間は、作業を続けることができます。
\nこの機能は新しいので､ドキュメントに書かれるべきです｡ django/docs/ref/forms/api.txt の 1068行目 (ファイルの最後) に追記してください:
The prefix can also be specified on the form class::\n\n >>> class PersonForm(forms.Form):\n ... ...\n ... prefix = 'person'\n\n.. versionadded:: 1.9\n\n The ability to specify ``prefix`` on the form class was added.\nこの新機能は将来のリリースに含まれるとともに、Django 1.9のリリースノート、ファイル docs/releases/1.9.txt 164行目以降の"Forms"のセクションに追加されています。
* A form prefix can be specified inside a form class, not only when\n instantiating a form. See :ref:`form-prefix` for details.\nドキュメントの書き方についてもっと知りたい場合は Writing documentation を参照してください｡ここでは､ ``versionadded` の書き方についてや､ ドキュメントのコピーをローカルでビルドしてみて､ HTML をプレビューする方法などが書かれています｡
\nTrac にアップロードされたり､他のDjangoに適応されるパッチを作りましょう｡パッチの内容を見るために､以下のコマンドを実行してください:
\n$ git diff\nチュートリアルの初めでチェックアウトした最初のリビジョンと､(修正した) 現在の Django のコピーとの違いを表示します｡
\nパッチを見終わったら､ q キーをタイプしたコマンドラインに戻りましょう｡パッチの内容が良さそうなら､以下のコマンドを実行して､現在のワーキングディレクトリにパッチを保存してください:
$ git diff > 24788.diff\nDjango のルートディレクトリに 24788.diff というファイルが作られるでしょう｡このパッチは変更のすべてを含んでおり､このようになります:
diff --git a/django/forms/forms.py b/django/forms/forms.py\nindex 509709f..d1370de 100644\n--- a/django/forms/forms.py\n+++ b/django/forms/forms.py\n@@ -75,6 +75,7 @@ class BaseForm(object):\n # information. Any improvements to the form API should be made to *this*\n # class, not to the Form class.\n field_order = None\n+ prefix = None\n\n def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,\n initial=None, error_class=ErrorList, label_suffix=None,\n@@ -83,7 +84,8 @@ class BaseForm(object):\n self.data = data or {}\n self.files = files or {}\n self.auto_id = auto_id\n- self.prefix = prefix\n+ if prefix is not None:\n+ self.prefix = prefix\n self.initial = initial or {}\n self.error_class = error_class\n # Translators: This is the default suffix added to form field labels\ndiff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt\nindex 3bc39cd..008170d 100644\n--- a/docs/ref/forms/api.txt\n+++ b/docs/ref/forms/api.txt\n@@ -1065,3 +1065,13 @@ You can put several Django forms inside one ``<form>`` tag. To give each\n >>> print(father.as_ul())\n <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>\n <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>\n+\n+The prefix can also be specified on the form class::\n+\n+ >>> class PersonForm(forms.Form):\n+ ... ...\n+ ... prefix = 'person'\n+\n+.. versionadded:: 1.9\n+\n+ The ability to specify ``prefix`` on the form class was added.\ndiff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt\nindex 5b58f79..f9bb9de 100644\n--- a/docs/releases/1.9.txt\n+++ b/docs/releases/1.9.txt\n@@ -161,6 +161,9 @@ Forms\n :attr:`~django.forms.Form.field_order` attribute, the ``field_order``\n constructor argument , or the :meth:`~django.forms.Form.order_fields` method.\n\n+* A form prefix can be specified inside a form class, not only when\n+ instantiating a form. See :ref:`form-prefix` for details.\n+\n Generic Views\n ^^^^^^^^^^^^^\n\ndiff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py\nindex 690f205..e07fae2 100644\n--- a/tests/forms_tests/tests/test_forms.py\n+++ b/tests/forms_tests/tests/test_forms.py\n@@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):\n self.assertEqual(p.cleaned_data['last_name'], 'Lennon')\n self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))\n\n+ def test_class_prefix(self):\n+ # Prefix can be also specified at the class level.\n+ class Person(Form):\n+ first_name = CharField()\n+ prefix = 'foo'\n+\n+ p = Person()\n+ self.assertEqual(p.prefix, 'foo')\n+\n+ p = Person(prefix='bar')\n+ self.assertEqual(p.prefix, 'bar')\n+\n def test_forms_with_null_boolean(self):\n # NullBooleanField is a bit of a special case because its presentation (widget)\n # is different than its data. This is handled transparently, though.\nおめでとうございます! Django への最初のパッチができました! パッチの書き方を習得したので､ Django のコードベースを改善するためにスキルを活かしましょう｡パッチを生成して､Tracのチケットに貼り付けるのは便利ですが､ git を使っている場合は､ git ワークフロー の利用がオススメです｡
\n変更をローカルでコミットしなかった場合は､ git のブランチを始めに戻すために以下を実行してください:
\n$ git reset --hard HEAD\n$ git checkout master\nDjango へのパッチを書き始める前に､貢献するために見ておいたほうがいい情報があります:
\nDjango のドキュメントの チケットをクレームして､パッチを送信する を読んでください｡ Trac でのエチケットやチケットをクレームする方法やパッチに適切なコーディングスタイルなど､重要なことを網羅できます｡
Django への初めての貢献者は 初めての貢献者へのドキュメント を読んでください｡Django に初めて協力する人たちへの良いアドバイスがあります｡
貢献について､より多くの情報を知りたいなら､ 貢献についての Django のドキュメント を参照してください｡そこにはたくさん有用な情報がありまし､質問があれば､このドキュメントが1番役に立ちます｡
ドキュメントをたくさん読んだ後は､実際のパッチを書けるのでチケットを探してみましょう｡ "easy picking" タグが付いたチケットを見つけてください｡このチケットは大抵はより簡単なものなので､初めての貢献者には適切でしょう｡ Django への貢献に慣れてきたあとは､難しく､複雑なチケットを書き始めれるでしょう｡
\n今すぐ始めたいなら (責める人はいません！)、 パッチが必要な簡単なチケット か パッチに改善が必要な簡単なチケット を見つけましょう。テストを書きなれているなら テストが必要な簡単なチケット でもよいでしょう。ただ、チケットのクレームに関するガイドラインに従ってください。 Django ドキュメントの チケットをクレームしてパッチを送る で記述されています。
\nチケットにパッチが追加されたあとは、別の人間の目でレビューされる必要があります。パッチをアップロードしたりプルリクエストを送信したあとは、チケットのメタデータから "has patch" フラグを設定してください。 "doesn't need tests" や、その他のメタデータはレビューのためにあります。貢献する際にはいつもスクラッチからパッチを書くというわけではありません。既存のパッチをレビューすることをまた素晴らしく役に立つ貢献です。詳細は Triaging tickets を参照してください。
\n