小さなものでも、コミュニティへ恩返しすることに興味がありますか？ たとえば、Django に直してほしいバグを見つけたり、ちょっとした機能を追加してほしいと思っているかもしれません。
\nその願いを叶える一番の方法は Django 自体にコントリビュートすることです。最初はすごく大変なことだと想像するかもしれませんが、あなたを助けてくれるドキュメント、ツール、コミュニティとともに多くの人が通る道でもあります。これからコントリビュートのプロセス全体を順番に詳しく解説していくので、例を通して理解できると思います。
\nこのチュートリアルでは、少なくとも Django がどのように動作するかについて基本的な理解を持っていることを期待します。つまり、 はじめての Django アプリ作成 にある既存のチュートリアルを一通り読んで慣れている必要があります。加えて、Python 自体をよく理解している必要があります。しかし、もしそうでなければ、 Dive Into Python は Python プログラマの初心者のための素晴らしい (そして無料の) オンラインブックです。
\nバージョン管理システムや Trac をよく知らない方でも、このチュートリアルとリンク先から、コントリビュートに必要な情報は十分得られます。しかし、Django に定期的に貢献したい場合は、このツールの詳細を知っておいた方がいいでしょう。
\nこのチュートリアルでは、できるだけ多くの方が使用できるように、可能な限り詳しく説明したいと思います。
\n\nWe'll be walking you through contributing to Django for the first time.\nBy the end of this tutorial, you should have a basic understanding of both the\ntools and the processes involved. Specifically, we'll be covering the following:
\nGit のインストール
Django 開発版の複製をダウンロードする
Django のテストスイートの実行
Writing a test for your changes.
Writing the code for your changes.
Testing your changes.
プルリクエストを送る
より多くの情報を得る方法
チュートリアルを終えたら、次は Django への貢献 を参照してください。このドキュメントには、多くの重要な情報が含まれており、Django に定期的に貢献したい方は是非一読してください。あなたの疑問への答えが見つかるはずです。
\n\n\nDjango へ貢献を行う上では、Django コミュニティをオープンで誰にでも開かれたものに保つよう心がけてください。 行動規範 をよく読み、それに従ってください。
\nFor this tutorial, you'll need Git installed to download the current\ndevelopment version of Django and to generate a branch for the changes you\nmake.
\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 に組み込まれている機能である 仮想環境 を使用することです。これにより、相互に干渉しないようにプロジェクトごとにインストールされたパッケージの別々のディレクトリを保つことができます。
例えばホームディレクトリ下の .virtualenvs/ にすべての仮想環境を置くことが出来ます。
次のコマンドで、新しい仮想環境を作成します:
\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新しいターミナルウィンドウを開くたびに仮想環境を有効にする必要があります。
\n\nその時点で有効な仮想環境の名前がコマンドライン上に表示されます。これによってどの仮想環境を利用しているのかが分かります。仮想環境のもとで pip によるインストールを行うと、表示されている仮想環境内にインストールされます。他の仮想環境やパッケージインストールによるシステムとは区別されます。
先に進んで、以前にクローンしたDjangoのコピーをインストールしてください:
\nLinux / macOS
$ python -m pip install -e /path/to/your/local/clone/django/\nWindows
...\\> py -m 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 contribution.
\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 contribution, especially if testing\nany changes to the UI.
\nDjangoプロジェクトの作り方については、 tutorial を参照してください。
\nDjango に貢献する際には、コードの変更が Django の他の領域にバグを持ち込まないようにすることが非常に重要です。変更を行った後もDjangoが動作するかどうかを確認する方法の1つは、Djangoのテストスイートを実行することです。すべてのテストに合格していれば、あなたの変更が機能し、Django の他の部分を壊していないことを合理的に確認することができます。 Django のテストスイートを実行したことがない人は、事前に一度実行して出力に慣れておくと良いでしょう。
\nテストスイートを実行するする前に cd tests コマンドを使って Django の tests/ ディレクトリに移動し、実行することでテストの依存関係をインストールします。
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m 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 の main ブランチは常に安定しているとは限りません。 main バージョンで開発を行う場合、 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" は一例です。新しいブランチ内で行ったすべての変更は、先ほどクローンしたコードのマスターコピーには影響しません。
\nIn most cases, for a contribution to be accepted into Django it has to include\ntests. For bug fix contributions, this means writing a regression test to\nensure that the bug is never reintroduced into Django later on. A regression\ntest should be written in such a way that it will fail while the bug still\nexists and pass once the bug has been fixed. For contributions containing new\nfeatures, you'll need to include tests which ensure that the new features are\nworking correctly. They too should fail when the new feature is not present,\nand then pass once it has been implemented.
\nA good way to do this is to write your new tests first, before making any\nchanges to the code. This style of development is called\ntest-driven development and can be applied to both entire projects and\nsingle changes. After writing your tests, you then run them to make sure that\nthey do indeed fail (since you haven't fixed that bug or added that feature\nyet). If your new tests don't fail, you'll need to fix them so that they do.\nAfter all, a regression test that passes regardless of whether a bug is present\nis not very helpful at preventing that bug from reoccurring down the road.
\nハンズオンでの例題に移りましょう。
\nこのチケットを解決するために、 make_toast() 関数に django.shortcuts モジュールに追加します。まずはこの関数を使うためのテストを書いて、関数の出力が正しいことを確認しましょう。
Djangoの tests/shortcuts/ フォルダへ移動して test_make_toast.py というファイルを新たに作ります。以下のコードを追加してください。
from 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 を返すかを確認します。
まだ django.shortcuts に変更を加えていないため、テストは失敗します。 shortcuts フォルダ内の全てのテストを実行して、どうなるか見てみましょう。 cd でDjangoの tests/ ディレクトリへと移動してから実行してください。
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nテストが正しく実行されれば追加したテストメソッドに対して、こちらのエラーとともに１つテストが失敗しているはずです。
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nテストがすべて通れば､上記した新しいテストを正しいフォルダ､クラスに追加したことを確認してください｡
\n続いては make_toast() 関数を追加します。
django/ フォルダに移動して shortcuts.py ファイルを開きます。最下行に以下を追加します:
def make_toast():\n return "toast"\nさて、先ほど書いたテストが成功したことを確認する必要があるので、追加したコードが正しく機能しているかどうかを確認できます。もう一度、Django の tests/ ディレクトリに移動して以下を実行します:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nテストはすべて成功するはずです。失敗した場合は、正しいファイルに対して正しく関数を追加しているかどうかを確認してください。
\nOnce you've verified that your changes and test are working correctly, it's\na good idea to run the entire Django test suite to verify that your change\nhasn't introduced any bugs into other areas of Django. While successfully\npassing the entire test suite doesn't guarantee your code is bug free, it does\nhelp identify many bugs and regressions that might otherwise go unnoticed.
\nDjango の全てのテストスイートを走らせるには cd で Django の tests/ ディレクトリ移動して実行してください:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nこれは新たな機能です。したがってドキュメントを作る必要があります。ファイル docs/topics/http/shortcuts.txt を開いて、このファイルの最終行に以下を加えます。
``make_toast()``\n================\n\n.. function:: make_toast()\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ドキュメントの書き方についてもっと知りたい場合は ドキュメントを書く を参照してください｡ここでは､ versionadded の書き方についてや､ ドキュメントのコピーをローカルでビルドしてみて､ HTML をプレビューする方法などが書かれています｡
Now it's time to review the changes made in the branch. To stage all the\nchanges ready for commit, run:
\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')\nWhen you're done previewing the changes, hit the q key to return to the\ncommand line. If the diff looked okay, it's time to commit the changes.
変更点をコミットするには、次のコマンドを実行します。
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nすると、コミットメッセージを入力するためのテキストエディタが開きます。 コミットメッセージガイドライン に従って、次のようにメッセージを入力します。
\nFixed #99999 -- Added a shortcut function to make toast.\nAfter committing the changes, send it to your fork on GitHub (substitute\n"ticket_99999" with the name of your branch if it's different):
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nプルリクエストは Django の GitHub ページ から作成できます。"Your recently pushed branches" の下にあなたのブランチが表示されているはずです。その下の "Compare & pull request" ボタンをクリックします。
\nPlease don't do it for this tutorial, but on the next page that displays a\npreview of the changes, you would click "Create pull request".
\nおめでとうございます！ これで Django へのプルリクエストの作成方法を学ぶことができました。応用テクニックについて詳しくは Working with Git and GitHub を読んでください。
\nこれで、Django のコードベースを改良する手助けができるようになりました。
\nBefore you get too into contributing to Django, there's a little more\ninformation on contributing that you should probably take a look at:
\nYou should make sure to read Django's documentation on\nclaiming tickets and submitting pull requests.\nIt covers Trac etiquette, how to claim tickets for yourself, expected\ncoding style (both for code and docs), and many other important details.
Django への初めてのコントリビューターは 初めてのコントリビューターへのドキュメント を読んでください｡Django に初めて協力する人たちへの良いアドバイスがあります｡
貢献について､より多くの情報を知りたいなら､ 貢献についての Django のドキュメント を参照してください｡そこにはたくさん有用な情報がありまし､質問があれば､このドキュメントが1番役に立ちます｡
Once you've looked through some of that information, you'll be ready to go out\nand find a ticket of your own to contribute to. Pay special attention to\ntickets with the "easy pickings" criterion. These tickets are often much\nsimpler in nature and are great for first time contributors. Once you're\nfamiliar with contributing to Django, you can start working on more difficult\nand complicated tickets.
\nIf you just want to get started already (and nobody would blame you!), try\ntaking a look at the list of easy tickets without a branch and the\neasy tickets that have branches which need improvement. If you're familiar\nwith writing tests, you can also look at the list of\neasy tickets that need tests. Remember to follow the guidelines about\nclaiming tickets that were mentioned in the link to Django's documentation on\nclaiming tickets and submitting branches.
\nAfter a ticket has a branch, it needs to be reviewed by a second set of eyes.\nAfter submitting a pull request, update the ticket metadata by setting the\nflags on the ticket to say "has patch", "doesn't need tests", etc, so others\ncan find it for review. Contributing doesn't necessarily always mean writing\ncode from scratch. Reviewing open pull requests is also a very helpful\ncontribution. See チケットをトリアージする for details.
\n