Django プロジェクトに協力するために¶

revision-up-to:	8961 (1.0)

Django を使うのを楽しいと思ってもらえたなら、 使い続ける 前にすこし待ってください。私達は多大な情熱をかけて、ユーザがコミュニティのメンバに貢献できるよう手助けしています。Django の開発を手伝うにはいくつもの方法があります:

Django について blog を書きましょう。私達は知っている限りの全ての Django 関係の blog をコミュニティのページで配信しています。このページに登録したい blog があるなら jacob@jacobian.org に連絡してください。
バグ報告や機能に関する要望をチケットトラッカに提出しましょう。私達が望んでいるバグ報告の提出方法の詳細はバグの報告を読んで下さい。
新たな機能を追加したり従来の機能を修正するパッチを提出しましょう。パッチの提出方法はパッチの提出を参照してください。
django-developers メーリングリストに参加して、 Django をよりよくするためのアイデアを皆で共有しましょう。どんな提案でも歓迎します。ただし私達は後ろだてになるコードがないスケールの大きな話には懐疑的です。
他のユーザが提出したパッチのトリアージ (選別) を行います。トリアージの手順については、後述のチケットのトリアージを参照してください。

Django 開発コミュニティに参加するのに必要な知識はこれだけです。このドキュメントの残りの部分では、開発コミュニティがどのようになっていて、どうやってバグを処理しているかについて詳しく説明し、メーリングリストやその他こまごまとした注意点について記述しています。

バグの報告¶

上手に書かれたバグ報告は 信じられないくらい 助けになります。とはいえ、バグ追跡システムでの作業はかなりのオーバヘッドを要するので、チケットトラッカをできるだけ有意義に使うよう協力していただけると助かります。特に:

必ず FAQ を読んで、自分の抱えている問題が既知のものでないか探して下さい。
必ずトラッカを検索して、自分の抱えている問題がファイルされていないか探して下さい。
必ず 最初に django-users で質問して、自分の考えていることがバグだということを確認してください。
必ず完結した、再現可能な、的確なバグ報告を書いて下さい。完全なコード断片やテストセットなど、可能な限り多くの情報を含めて下さい。問題に対する詳細かつ明瞭な説明と、問題を再現するための手順を含めてください。小さなテストケースでバグを再現できれば最良のバグ報告になります。
決して サポート質問にチケットシステムを 使わないで下さい。 質問は django-users リストや #django IRC チャネルでお願いします。
決して スケールの大きな機能の提案にチケットシステムを 使わないで下さい。 Django のコアに関わる大きな変更は、取り掛かる前に必ず django-developers リストで議論します。
決して “wontfix” にマークされた問題を 開き直さないで下さい。 “wontfix” マークは決定事項であり、この問題についてはこれ以上修正できないか、修正する予定はないのです。納得できなければ、 django-developers で質問してください。
決して 長い議論をチケットシステムで 行わないで下さい。 チケットシステムでは議論内容がじきに失われてしまうからです。チケットの内容について議論になりそうなときは django-developers に場所を移して下さい。
バグ報告をチケットに登録したことだけを django-developers にポスト しない でください。チケットを登録すると、別のメーリングリスト (django-updates) にメールが送信されます。開発者やトリアージ担当者はこのメーリングリストを監視しているので、登録したことがすぐ分かるからです。

セキュリティ問題の報告¶

セキュリティ問題の報告は security@djangoproject.com にお願いします。このメーリングリスト経験豊かで信頼できる Django 開発者だけが購読でき、アーカイブは非公開になっています。

Django に脆弱性が発見された場合、私達は以下のように行動します:

報告者に対して、報告を受けとったことと、脆弱性がまもなく修正されることを知らせます。修正までのおおまかなタイムラインを示し、報告者に対して、アナウンスを行うまでにどのくらいの間この問題を秘密にしておけるか問い合わせます。
現在のバージョンと、二つ前までのリリースに対するパッチを含む修正版の開発に必要な期間、他の全ての開発を停止します。
脆弱性と修正版をアナウンスするする日取りを決めます。パッチを適用する側と脆弱性を不正利用する側の間の「軍拡競争」を抑えるため、私達はセキュリティ問題を即座にアナウンスしません。
影響を受けるバージョンの Django を使っているユーザのうち、私達が把握している人全員に事前に通知します。この通知は個人宛の電子メールで行われます。メールには脆弱性に関するドキュメントと該当パッチへのリンク、そしてこの脆弱性を公式の公開日まで秘密にしておくよう要請する文が入っています。
あらかじめ決めておいた日取りに基づいて、脆弱性と修正版を公開し、アナウンスします。通常は新たなバージョンの Django リリースを意味しますが、場合によっては現在のリリースに対する単なるパッチになります。

パッチの提出¶

Django のコードに対するパッチはつねに大歓迎です。実際、パッチつきのバグ報告は、パッチのないものよりも はるかに 素早く修正されます。

チケットをクレーム（審査請求）する¶

世界中に何百人ものコントリビュータを擁するようなオープンソースプロジェクトでは、コミュニケーションを効率的に進めることで、同じ作業が何度も繰り返されるのを防ぎ、コントリビュータができるだけ効果的に振る舞えるような配慮が重要です。そのため、コントリビュータがチケットをクレームし、他の開発者たちに、何らかのバグ報告や機能提案がなされていることを知らせるという方針をとります。

Django プロジェクトに何らかの貢献をしたいと考えていて、 (コード作成能力や、 Django の内部に関する知識、時間的な余裕から) 必要な修正を行えるのなら、以下のステップに従ってチケットをクレームしてください:

チケットシステム上にアカウントを作成します。
自分の提起したい内容がまだチケットトラッカ上になければ、新たに作成します。
自分の提起したい内容がすでにチケットトラッカ上にあるのなら、そのチケットの “Assigned to” セクションを調べて、誰かによってクレーム済みでないか確認してください。 “nobody” になっていれば、そのチケットはクレームできます。すでに誰かのアカウント名が入っているのなら、他のチケットを探してクレームするか、その問題に関わっている開発者に連絡をとって、チケット解決に手を貸してください。
まだログインしていなければ、自分のアカウントでログインしてください。ログインするには、チケットページの右上にある “Login” をクリックします。
チケットをクレームするには、チケットページの下にある、”Accept ticket” の隣のラジオボタンをクリックしてから、 “Submit changes” をクリックします。

チケットをクレームしたら¶

チケットをクレームした人は、そのチケットが時代おくれにならないよう作業せねばなりません。チケットに時間を割けないのなら、クレームを解除するか、そもそもクレームしないようにしてください！

チケットのトリアージ担当者たちは、クレーム済みのチケットを何度も調べて、各々のチケットに進捗があるかどうか調べます。クレーム状態にあるチケットが進捗しないまま 1 週間以上過ぎた場合、チケットが独占されつづけないよう、クレームを解除してほしい旨問い合わせる場合があります。

チケットをクレームしてから、コードを書くまでにしばらく (数日から数週間) かかる場合、何らかのコメントをポストして、その旨を通知してください。更新がなく、進捗レポートの要求に対する返事もない場合、チケットを無効にする場合もあります。まずは連絡第一です!

どのチケットをクレームすべきか¶

もちろん、わざわざチケットをクレームするまでもない場合もあります。ドキュメントのタイプミスや、ほんの数分あれば修正できるような小さなバグの場合には、チケットのクレームまでする必要はありません。単にパッチを投稿して、そのままにしておいてください。

パッチ形式¶

Django のコーディングスタイルに従っているか確認してください。
svn diff コマンドの返す書式のパッチを提出してください。ただし、コードよりも英語で変更点を説明した方がはるかに分かりやすい場合は例外です。例えばインデントはよくある例です。というのも、コードの違いがインデントでしかない場合、パッチを読むのはとても大変だからです。
パッチを作るときには、常に trunk ディレクトリの最上位の階層、すなわち、 django, docs, tests, AUTHORS などがある場所で svn diff を実行してください。こうしてパッチを作ったほうが他の人が適用しやすいからです。
チケットトラッカで、 “attach file” ボタンを使ってチケットにパッチを添付してください。一行のパッチでないかぎり、チケットの説明やコメントの中にパッチを 入れないで 下さい。
パッチファイルの名前には .diff 拡張子をつけて下さい。そうすることで、チケットトラッカは構文のハイライト強調を正しく行うので助かります。
チケットの詳細情報欄にある「パッチ付き」(“Has patch”) ボックスにチェックを入れてください。チケットがパッチつきであることが分かりやすくなり、チケットシステムがそのチケットをパッチつきのチケットのリストに追加してくれます。
問題を解決したり機能を追加するためのコードはパッチの重要な部分ですが、それだけではいけません。よいパッチというものには必ず回帰テストが付属していて、問題が解決されたことを検証できる (そして将来同様の問題が再発しないようにできる) ものです。
パッチ中のコードが新たな機能や既存の機能に対する変更をもたらす場合、パッチにはドキュメントも含めてください。

重要パッチ¶

「重要 (non-trivial)」パッチとは、単なるバグフィクスに留まらず、Django に新たな機能をもたらし、何らかの設計上の判断を迫るようなパッチです。

重要パッチを提出する場合には、その問題について django-developers で議論済みであるという証明を含めてください。自分のパッチが重要パッチかどうか判断しかねる場合には問い合わせてください。

チケットのトリアージ¶

残念ながら、チケットトラッカに届くバグ報告全てが、上に述べたチケットの要件を満たしているわけではありません。パッチの添付されたチケットもたくさんありますが、それら全てがよいパッチの要件を満たしているわけでもありません。

こうした状況の打開を手助けする一つの方法に、他のユーザが報告したバグのトリアージ (選別) 作業があります。この作業には献身的なボランティア 2 名が常時携わっていますが、手助けをしてくれる人は常に歓迎です。

トリアージ作業のワークフローの大半は、チケットの「トリアージ段階 (triage stage)」というフィールドに関わる作業です。このステージとは、あるチケットがライフサイクルのどの段階にあるかを示す指標です。ステージフラグやその他のフラグによって、誰のどんなチケットが処理待ちになっているかがわかります。

百聞は一見にしかずですから、例を挙げて説明しましょう:

チケット処理の流れには、まず、 2 種類の公認の役割があります:

コア開発者: コミット権限を持ち、コードに関する重大な決定や、大部分のコード作成を行う人です。
トリアージ担当者: Django コミュニティでの長期にわたる実績を持った信頼のおけるメンバです。その実績に基づいて、コア開発者はチケット単位のより小規模な決定権を委譲しています。

次に、トリアージ作業には以下の 5 つのステージがあります:

チケットは「未レビュー(unreviewed)」の状態からスタートします。まだだれもチケットを調べていない状態です。
「設計判断待ち(design decision needed)」は、「このコンセプトには設計上の判断が必要」であり、チケットのコメント欄か、 django-developers 上で議論すべきであることを示しています。設計判断待ちのステップは、原則として機能追加リクエストのチケットにしかありません。ただし、意見や解釈によってはバグと見なされ得るような問題に対して使われる場合もあります。明らかなバグ (クラッシュする、クエリ結果がおかしい、標準からかけ離れた動作) の場合、このステップは飛ばして「承認」に進みます。
チケットの内容に従った修正が受け入れられた場合、「承認 (accepted)」ステージに移行します。このステージは全ての作業が終わった状態です。
チケットは “Someday/Maybe” 状態に移行させられる場合があります。これは、該当チケットに述べられている内容に対して、素晴らしいパッチが提供された時点でフレームワークに追加しようと考えていることを示します。この状態に移行したチケットの優先度は高くありません。
チケットにパッチが関連づけられている場合 (下記参照)、トリアージ作業者はパッチをレビューします。パッチの内容が完璧なら、「チェックイン可 (ready for checkin)」にマークされ、コア開発者にパッチをレビューしてチェックすべきであることを知らせます。

ワークフローにはもう 1 つ、一連のフラグがあります。フラグは各チケットを「チェックイン可」にするために必要な条件のうち、何が満たされていて何が必要かを示します:

「パッチあり (has patch)」: チケットにパッチが添付されていることを示します。このフラグのついたパッチはトリアージ担当者によってレビューされ、条件を満たした「よいパッチ」であるかどうか調べられます。
「ドキュメント不足 (needs documentation)」: パッチつきのチケットに対して、ドキュメントが必要であることを示します。コードベースに修正をチェックインする条件として、完全なドキュメントが必要です。
「テスト不足 (needs tests)」: パッチに単位テストが必要であることを示します。上ど同様、条件として有効なパッチが必要です。
「パッチに改良の余地あり (patch needs improvement)」: チケットにパッチが 付属している が、チェックインするには修正の余地があることを示します。パッチが古くてきれいに当てられなくなってしまっている場合や、コードがコーディング基準に従っていないことを示します。

チケットは色々な形で解決されます:

「修正済み (fixed)」: パッチが Django に取り込まれ、問題が解決されると、コア開発者はチケットを fixed にマークします。
「無効 (invalid)」: チケットの内容が不正確であると判断された場合に使われます。無効扱いは、チケットの報告している問題が何らかのユーザの手違いに起因している、 Django に関係ない問題である、あるいは、バグ報告でも機能リクエストでもない (例えば、初心者の中にはチケットにサポート質問を書く人がいます) と判断されたことを示しています。
「修正の予定なし (wontfix)」: 修正要求を Django に取り込むのは不適切であると判断した場合、コア開発者はチケットを wondfix にマークします。 wontfix へのマークは、通常は django-developer メーリングリストでの議論の末に選択されることなので、気になる議論があったらぜひ参加してください。
「他のチケットと重複 (duplicate)」: 他のチケットで同じ問題がカバーされている場合にはチケットを duplicate にマークします。重複したチケットをクローズして問題解決のための議論を 1 箇所にまとめ、話を進めやすくするためです。
「再現不能 (worksforme)」: チケットに十分な情報がなく、問題を再現できない場合に使われます。

あるチケットが明らかに誤ってクローズされた – クローズされたチケットで提起されている問題が依然として生じている場合や、別の問題が生じた場合、あるいはトリアージ作業でミスが起きている – 場合には、そのチケットを再度開いて (reopen)、その理由を記載してください。また、コア開発者が “wontfix” にマークしたチケットを reopen しないでください。

一般コミュニティメンバによるトリアージ¶

コア開発者やトリアージ担当者がチケットのトリアージ作業で重要な決定を行う一方で、一般コミュニティのメンバもまた、トリアージ作業に参加できます。具体的には、以下のようなトリアージ補助があります:

「レビュー待ち」状態のチケットを、「無効」、「再現不能」、「重複」といった理由でクローズできます。
「レビュー待ち」状態のチケットを、設計判断が必要な場合には「設計判断待ち」に、明らかなバグの場合には「承認」に昇格させられます。
「テスト不足」「ドキュメント不足」のチケットを修正したり、「パッチあり」フラグが正しくセットされていないチケットを修正できます。
古いチケットに何も変化がないまま長時間経過している場合、その問題が解決されているにもかかわらずチケットがクローズされず放置されていないか調べられます。
チケットをクレームしたにもかかわらず、最近動きのないチケットオーナに連絡して、返事が 1 週間以上ない場合にはチケットのクレームを失効させられます。
チケットの傾向と本質的な問題を分析できます。 Django の特定の部分に対するバグ報告が集中している場合、コードのリファクタを検討する必要があることを示しています。何らかの傾向が見られるのなら、(問題のチケットを引きあいに出して) django-developers に問題提起してください。

とはいえ、一般コミュニティのメンバがチケットデータベースを操作する際には、以下の点に気をつけてください:

チケットを「修正の予定なし」で閉じては なりません 。チケットの生死を最終的に決めるのはコア開発者で、それも通常はコミュニティと相談した後だからです。
つづりの間違い修正やドキュメントのリンク修正といった 些細な 変更でない限り、チケットを「チェックイン可」に昇格させては なりません 。
コア開発者が下した決定を差し戻しては なりません 。議論に納得できないのなら、 django-developers にメッセージをポストしてください。
慎重に振る舞ってください。チケットの状態を変更すべきか迷うような場合には、変更してはなりません。そんな場合には、チケットに自分のコメントを残すか、 django-developers にメッセージをポストしてください。

翻訳の提出と維持¶

admin サイトやバリデータのエラーメッセージなど、Django は様々な部分で国際化されており、ユーザの言語設定に従って様々なテキストを表示します。この機能を実現するために、Django は共通の国際化メカニズムを使っています。国際化メカニズムはどのアプリケーションからも利用できます。利用法は i18n のドキュメント で解説しています。

翻訳カタログは世界中の Django ユーザによる貢献でできています。間違った翻訳や、まだ翻訳存在しない言語に新たな翻訳を追加したい場合は以下のようにします:

Django i18n メーリングリストに参加して自己紹介してください。
i18n のドキュメント に従って翻訳を作成してください。カタログの生成には django-admin.py makemessages ツールを使います。 Django 全体のカタログを生成する場合、 Django のソースツリーのトップレベルにある django ディレクトリでコマンドを実行してください。

このツールは、 Django のソースツリー全体を走査して、翻訳対象としてマークされた文字列を取り出します。メッセージカタログファイルは conf/locale ディレクトリ以下に生成（または更新）されます。（例えば、 pt-BR ロケールであれば、ファイルは conf/locale/pt-br/LC_MESSAGES/django.po に書き出されます。）
django-admin.py compilemessages -l <lang> を実行して、警告がでないのを確認してください。
上の二つのステップを、 djangojs ドメインに対しても実行してください。 (django-admin.py のコマンドラインに -d djangojs オプションを付加して実行します)
最新の Subversion trunk に対して、 .po ファイルの差分を作成してください。
Django のチケットシステムで新しいチケットを作成し、 Component フィールドを Translations に設定して、パッチを添付して提出してください。

コーディングスタイル¶

コードを書いて Django に取り込みたいなら、以下のコーディング標準に従って下さい:

特に指定のない限り PEP 8 に従って下さい。

pep8.py のようなツールを使えば、コーディング標準に従っているかどうかをチェックできます。とはいえ、 PEP 8 はガイドにすぎません。まずは、周辺のコードのスタイルを尊重してください。
インデントにはスペース 4 つを使います。
変数名、関数名、メソッド名には camelCase ではなくアンダースコアを使って下さい (たとえば poll.getUniqueVoters ではなく poll.get_unique_voters())。
クラス名 (やクラスを返すファクトリ関数) には InitialCaps を使ってください。
国際化の必要な全ての文字列をマークしておいてください。詳しくは i18n ドキュメント を参照してください。

docstring 内では、下記のような “action word” を使ってください:

def foo():
    """
    Calculates something and returns the result.
    """
    pass

以下のような書き方をしてはなりません:

def foo():
    """
    Calculate something and return the result.
    """
    pass

コード中に自分の名前を埋め込まないでください。Django プロジェクトでは、コードの開発者や貢献者の名前がコード中に散逸しないようにするため、 AUTHORS ファイルにまとめて記載するというポリシを採用しています。ほんのちょっとした変更でないかぎり、ご自分のパッチに AUTHORS への変更を加えて頂いてもかまいません。

テンプレートのスタイル¶

Django テンプレートコード内では、波括弧とタグコンテンツの間に 1 個 (1 個だけ) スペースをいれて下さい。

[正]:
```
{{ foo }}
```
[誤]:
```
{{foo}}
```

ビューのスタイル¶

Django のビューを書くときには、最初のパラメタは必ず request という名前にしてください。

[正]:
```
def my_view(request, foo):
    # ...
```
[誤]:
```
def my_view(req, foo):
    # ...
```

モデルのスタイル¶

フィールド名は全て小文字で、キャメルケース (camelCase のような書き方) はせず、アンダースコアを使います。

以下のような書き方をします:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

以下のような書き方をしてはなりません:

class Person(models.Model):
    FirstName = models.CharField(max_length=20)
    Last_Name = models.CharField(max_length=40)

class Meta はフィールドの定義を書いた後に書きます。また、フィールド定義とクラス定義の間には一行空行を入れます。

以下のように書きます:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

    class Meta:
        verbose_name_plural = 'people'

以下のような書き方をしてはなりません:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)
    class Meta:
        verbose_name_plural = 'people'

以下のような書き方もよくありません:

class Person(models.Model):
    class Meta:
        verbose_name_plural = 'people'

    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

モデルの内部クラスや標準メソッドの順番は以下のようにします (ただし、どれも必須ではないので省略してもかまいません):
- 全てのデータベースフィールド
- class Meta
- def __unicode__()
- def __str__()
- def save()
- def get_absolute_url()
- カスタムのメソッド定義
choices をモデルフィールドに定義する場合、選択肢は、各選択項目のタプルからなるタプルで定義します。定義はモデルモジュールの冒頭か、各モデルクラスのすぐ上に置き、全て大文字の変数名を付けます。例えば以下のようにします:
```
GENDER_CHOICES = (
    ('M', 'Male'),
    ('F', 'Female'),
)
```

ドキュメントの形式¶

私達は、ドキュメントの一貫性と読みやすさをとても重視しています (なんといっても、 Django はジャーナリズムの中で生まれましたからね！)

_How to document new features:

新たな機能のドキュメント化¶

私達は、ドキュメントをコードと同じように扱います。すなわち、可能な限り改善を重ねたいと思っているのです。この節では、ドキュメントの書き手に、有意義でエラーの少ないドキュメントの変更方法を説明します。

ドキュメントの変更には、二つの形式があります:

一般的な改善 -- タイプミス、誤った内容の修正、明確な文章への修正や、例題の追加です。
新たな機能説明 -- 前回のリリース以降に追加された機能のドキュメントです。

私達はドキュメントを以下のポリシに従って作成しています:

新たな機能に関するドキュメントを追加する場合、必ず該当機能が開発版の Django でのみ使用可能な旨を明記せねばなりません。ドキュメントの読み手は、開発版ではなく、最新のリリースを使っていると想定してください。

新しい機能を説明するときには、ドキュメントの先頭に ".. versionadded:: X.Y" を付加します。オプションで一行コメントを入れることもできます。 ".. versionadded:: X.Y" の後には必ず空行を入れてください。

一般的な改善や API の変更は、 ".. versionchanged:: X.Y" ディレクティブで強調します（フォーマットは versionadded と同じです）。

ReST ファイル作成のガイドライン¶

私達は、 ReST ドキュメントを作成するときに、以下のガイドラインに従っています:

章や節の題名では、最初の文字と適切な名前のみ大文字で書きます。
ドキュメントは幅 80 文字以内で折り返します。ただし、コード例を示す際に複数行に分けると著しく読みにくくなる場合や、その他妥当な理由がある場合は例外です。

よく使う用語¶

ドキュメント中でよく使われる用語の書き方を以下に示します:

Django -- フレームワークそのものを指す場合には、頭文字を大文字にします。 Python コード中や djangoproject.com のロゴでは小文字です。
e-mail -- ハイフンを入れます。(和訳では「メール」と書いています)
MySQL
PostgreSQL
Python -- 言語そのものを指す場合には頭文字を大文字にします。
realize, customize, initialize, etc. -- "-ise" ではなく、アメリカ語表記です。
SQLite
subclass -- 動詞、名詞を問わず、ハイフンを入れず一つの単語で表します。
Web, World Wide Web, the Web -- ワールドワイドウェブを指す場合には、常に Web の W は大文字です。
- Web site -- Web を大文字にして、二つの単語を繋げません。

Django 固有の用語¶

model -- 頭文字は小文字です。
template -- 頭文字は小文字です。
URLconf -- "URL" は大文字、 "conf" は小文字です。
view -- 頭文字は小文字です。

コードの commit¶

Django の Subversion リポジトリにコードをコミットする場合には以下のガイドラインに従って下さい:

中規模から大規模な変更 (「中規模から大規模」の判断は各自に任せます) の際には、変更前に django-developers メーリングリストに相談を持ち込んで下さい。

django-developers に持ち込んだ話題に対して返事がなかった場合、自分のアイデアが素晴らしく、すぐにでも実装すべきだと皆が思ったため誰も何も言わないのだと勘違いしないでください。 Django の開発指揮者はメーリングリストの議論にすぐに割ける時間を持ち合わせていないので、返事には数日待たねばならない場合もあるのです。
詳しいコミットメッセージを過去形で書いて下さい。現在形を使ってはなりません。
- 良い例: "Fixed Unicode bug in RSS API."
- 悪い例: "Fixes Unicode bug in RSS API."
- 悪い例: "Fixing Unicode bug in RSS API."
ブランチにコミットする場合、コミットメッセージの先頭にブランチ名を付けて下さい。例えば "magic-removal: Added support for mind reading." のようにします。
意味のある変更のまとまりであるかぎり、できるだけ細かい変更に分けてコミットしてください。つまり、たまに大きなコミットをするのではなく、小さなコミットを頻繁に行うようにしてください。例えば、機能 X を実装していて、その機能の実現にライブラリ Y の修正が必要なら、まず Y の修正をコミットして、次に X を別にコミットしてください。これだけで、 Django のコア開発者全員が変更を追うための 大きな 助けになります。
コミットによって Django チケットトラッカの何らかのチケットをクローズする場合、コミットメッセージの先頭に "Fixed #abc" というメッセージを入れて下さい。 "abc" はコミットによって修正されるチケットの番号です。例えば "Fixed # 123 -- Added support for foo" のようにします。私達は Subversion と Trac を結びつけているので、この形式のメッセージを使って commit した場合、関連するチケットを自動的にクローズし、完全なコミットメッセージをコメントとしてチケットに追加します。

コミットによってブランチのチケットをクローズする場合、ブランチ名を先にもってきます。例えば "magic-removal: Fixed #123 -- Added whizbang feature." のようにします。

ちなみに、この機能は Trac の post-commit フックで実現しています。
コミットメッセージで Django チケットトラッカの何らかのチケットを参照し、かつチケットを 閉じない 場合、 "Refs #abc" というフレーズを入れて下さい。 "abc" はコミットで参照しているチケットの番号です。私達は Subversion と Trac を結びつけているので、この形式のメッセージを使って commit した場合、関連するチケットに完全なコミットメッセージをコメントとして追加します。

単体テストの作成¶

Django には独自のテストスイートが付属しています。テストは tarball 内の test ディレクトリ下にあります。ポリシとして、常に全てのテストがパスするようにしています。

テストでは以下の項目をカバーしています:

モデル API とデータベース API (tests/modeltests/)。
その他、Django のコア内にあるテスト (tests/regressiontests)
contrib アプリケーション (django/contrib/<contribapp>/tests, 下記参照)

テストスイートに対する協力は何でも歓迎します!

Django のテストは全て、 Django に付属のアプリケーションテストインフラを使っています。テストの書き方の詳細は Django アプリケーションのテスト を参照してください。

単体テストの実行¶

テストを実行するには、 tests/ ディレクトリ下に移って以下のように入力します:

./runtests.py --settings=path.to.django.settings

そうです。テストには設定モジュールが必要です。とはいえ、必要なのは DATABASE_ENGINE を含むデータベース接続に関する情報です。また、全てのテストをパスするには、 ROOT_URLCONF 設定 (この値は単にあればよいだけで、内容は無視されます) を指定しておかねばなりません。

sqlite3 バックエンドを使っているなら、設定はこれだけで十分です。一時データベースはテスト実行時にメモリ上に生成されます。

sqlite3 以外のバックエンドを使っている場合は、以下のような設定が必要です:

DATABASE_USER を、対象データベースに存在するユーザ名に設定する必要があります。
DATABASE_NAME を、実際に存在して、かつユーザが接続可能なデータベースの名前に設定せねばなりません。ただし、ユニットテストはこのデータベースを操作しません。テストランナは、 DATABASE_NAME の前に test_ を付けた新たなデータベースを作成し、テスト終了後にこのデータベースを削除します。従って、データベースユーザには、 CREATE DATABASE を実行する権限がなければなりません。

また、データベースのデフォルト文字セットを UTF-8 にしているか確認してください。データベースサーバのデフォルト文字セットが UTF-8 に設定されていないのなら、 TEST_DATABASE_CHARSET に文字セットを指定する必要があります。

テストを全て実行したければ、以下の依存モジュール全てをインストールしておく必要があります:

これらの依存モジュールはなくても構いませんが、インストールされていなければ、関連するテストは飛ばして実行されます。

ユニットテストの一部（サブセット）を実行したい場合は、 runtest.py コマンドラインの後にテストモジュールの名前を追加してください。モジュール名は、 tests/modeltests および tests/regressiontests 以下のディレクトリ名を参照してください。

例えば、 Django が PYTHONPATH 上になく、 settings.py が tests/ ディレクトリにある場合で、汎用リレーション (generic relation) と国際化 (internationalization) だけをテストしたければ、以下のようにタイプします:

PYTHONPATH=..
./runtests.py --settings=settings generic_relations i18n

contrib アプリケーション¶

django/contrib 以下のアプリケーションのテストは、 django/contrib/ 以下のそれぞれのディレクトリ下にある test.py に収められています。 (テストを複数のモジュールに分割したければ、 tests ディレクトリを使ってください。)

アプリケーションのテストを見つけさせるには、アプリケーション内に models.py を入れていなければなりません (ファイルは空でもかまいません)。 URL をマップする必要があるのなら、 tests/urls.py を入れてください。

特定の contrib アプリケーション (例えば markup) だけをテストするには、上で述べたのと同じ方法を使います:

./runtests.py --settings=settings markup

機能に関する要望¶

私達は常に Django を改良しようと努めています。その中で、皆さんから寄せられる要望は一つの鍵になっています。効果的に要望を出すコツをいくつか紹介しておきます:

チケットトラッカではなく、 django-developers に要望を出して下さい。メーリングリストの方が多くの人の目に触れやすいからです。
不足している機能と、それをどのように実装すればよいと思っているかを、すっきりと、かつ詳細に説明してください。可能ならサンプルコード (実際に動かなくても構いません) をつけてください。
なぜその機能を取り入れたいのかを説明してください。自明な場合もありますが、 Django は実際の開発者が実際の仕事に使うために設計されているので、ある機能がどのようにユーザの役に立つのかを説明する必要があります。

ほとんどのオープンソースプロジェクトと同じく、コードは大きな説明力を持っています。追加したい機能のコードを書く意志があるか、(さらに望ましいのは) すでに書き上げているのなら、ずっと受け入れられやすくなるでしょう。大がかりな機能で、複数の開発者が必要になりそうなら、いつでも喜んで実験用ブランチをリポジトリに作成します。詳しくは次節を参照してください。

ブランチの管理ポリシ¶

一般に、ほとんどの開発は trunk で行われており、 trunk は安定に保たれています。 trunk のコードは、いついかなるときでも実運用サイトを動作させられなければなりません。

このため、大規模なアーキテクチャ上の変更、一つのパッチに収まらないくらい大きな変更を伴う場合や、多くの人が関わる必要のある変更の場合には、専用のブランチを作成します。例えば i18n ブランチを見てください。この手の変更を行いたいと考えていて、作業をしたい場合には、 django-developers でブランチを作成してもらうよう問い合わせて下さい。変更を試すのに必要な文だけのブランチを作成します。

ツリーの一部にしか作業しない場合でも、常に Django ツリー全体のブランチを作成します。これはブランチへのスイッチ作業を苦痛なく行えるようにするためです。

ブランチで作業している開発者は、 trunk の変更を定期的にブランチにマージせねばなりません。少なくとも週に一度はマージしてください。 trunk からマージを行う度に、マージとリビジョン番号を commit メッセージに記載してください。

ブランチが安定していて、 trunk へのマージ準備が完了したら、 django-developers にアラートを投稿します。

あるブランチがマージされると、そのブランチは「死んだ」ものとみなされます。死んだブランチには書き込めなくなり、古いブランチは定期的に「刈り取られ」ます。 SVN への世話焼きを最小限にするため、ブランチから trunk へのマージは一度しか行いません。

ブランチを使う¶

ブランチをテストするには、二つの作業が必要です:

該当するブランチのコードを Subversion から取得します。
Python の site-package ディレクトリが、該当ブランチの django を含むように設定します。

Subversion からコードを取り出す¶

ブランチコードの最新版を入手するには Subversion を使います:

svn co http://code.djangoproject.com/svn/django/branches/<branch>/

<branch> はブランチの名前です。ブランチの名前についてはブランチ名一覧を参照してください。

既存の Django を Subversion からソースコードをチェックアウトして使っている場合には、ディレクトリ全体を特定のバージョンに自動的に変換できます。 django ディレクトリの下で以下のコマンドを実行してください:

svn switch http://code.djangoproject.com/svn/django/branches/<branch>/

svn co ではなく svn switch を使う利点は、 switch コマンドを使った場合、ローカルコピー上で既に変更済みの内容についてはファイルを変更しない点にあります。 switch はローカルコピー上の変更を "スイッチ先の" コードにマージします。 svn switch には欠点もあります。それは、ローカルコピー上でコードに変更を加えた場合、スイッチ先のコードにも同じ部分に変更があると衝突するという問題です。

(svn switch を使う場合には、次の節で述べるような、Pythonのモジュール検索パスを変更する操作は必要ありません。)

Python に別のバージョンの Django を使わせる¶

ブランチのコードを取り出したら、ブランチの site-packages ディレクトリの構成を変更して、ブランチ版の django ディレクトリを使えるようにする必要があります。 (site-packages ディレクトリは /usr/lib/python2.4/site-packages や /usr/local/lib/python2.4/site-packages, C:\Python\site-packages などにあります。)

もっとも簡単な方法は、元の django ディレクトリを django.OLD のような別の名前に変えて、 trunk などから取り出したバージョンのコードをコピーし、名前を django に変更します。

別の方法として、 django と言う名前のシンボリックリンクを作成して、特定のブランチの django パッケージの場所を指すという方法もあります。元に戻したい場合には、シンボリックリンクが元のコードを指すように変更しなおすだけです。

第三の方法は、パスファイル (<something>.pth) を使うというものです。この方法は、 (シンボリックリンクを使えない Windows を含む) 全てのシステムで利用できます。まず、 site-packages ディレクトリに、 django という名前のファイルやディレクトリ、シンボリックリンクがない状態にしてください。次に、 django.pth という名前のテキストファイルを作成して、 site-packages ディレクトリの直下に保存します。このファイルには、使いたい Django の置かれているパスを一行で記述します。コメントを追加しても構いません。複数のブランチを指定できるようにしたパスファイルの例を以下似示します。特定のブランチ (例えば 'trunk') を使いたい場合、その行のコメントを解除して、他の行を全てコメント化します:

# トランク (trunk): svn リポジトリの
#   http://code.djangoproject.com/svn/django/trunk/
# からチェックアウトしたもの
#
/path/to/trunk

# ブランチ (branch): ブランチ名 <branch> を svn リポジトリの
#   http://code.djangoproject.com/svn/django/branches/<branch>/
# からチェックアウトしたもの
#
#/path/to/<branch>

# Windows の場合は以下のような形式にします:
# C:/path/to/<branch>

Django 0.95 やそれ以前のバージョンをインストールしていて、インストールに python setup.py install を使った場合、 django ではなく Django-0.95-py2.4.egg といった名前のディレクトリになっているでしょう。この場合、 setuptools.pth を編集して、該当する Django の .egg の書かれた行を削除してから、 django のブランチを site-packages にコピーします。

公式リリース¶

Django のリリース番号は以下のようにして付けられます:

バージョンは A.B または A.B.C という形式でつけられます。
A はメジャーバージョン番号で、増えるのは Django に重大な変更が加えられ、変更が必ずしも以前のバージョンと互換でない場合だけです。従って、 Django 6.0 で動いたコードは Django 7.0 では動かなくなるかもしれません。
B はマイナーバージョン番号で、比較的大きいながらも後方互換性を保った変更の際に増えます。 Django 6.4 向けに書かれたコードは Django 6.5 でも動作するでしょう。

マイナーリリースでは、以前のリリースの特定の機能を撤廃することがあります。バージョン A.B の機能が撤廃された場合、撤廃された機能は A.B+1 では動作します。 A.B+2 では PendingDeprecationWarning 警告を送出しますが動作します。 A.B+3 では完全に機能を削除します。メジャーポイントリリースでは撤廃済みの仕様を全て削除します。
C はマイクロバージョンで、バグやセキュリティ修正の度に増えます。マイクロバージョンは以前のマイクロバージョンと 100% 後方互換性を保ちます。
場合によってはリリース候補 (release candidate) を作成します。リリース候補のバージョン番号は A.BrcN の形式で、 A.B の N 番目のリリース候補であることを表します。

以上のバージョン番号スキームの例外として、1.0 以前の Django のコードがあります。 1.0 リリース以前のコードでは、後方互換性を全く保証していません。

Subversion 上では、 Django の各リリースは tags/releases_ でタグづけされています。trunk 由来ではないバグフィクスリリースやセキュリティ修正リリースを出す必要画ある場合、該当リリースは branches/releases にコピーされ、バグフィクスリリースになります。

仕様に関する決定¶

ある仕様の要望が出て議論が始まると、そのうち仕様を取り入れるべきか棄却すべきかという決定をせねばなりません。

私達は、可能な場合はいつでもまずおおまかな合意を形成しようと試みます。その後、たいていは django-developers において、その機能について正式でない投票を行います。投票では、 Apache や Python で使われている形式を採用しており、投票は +1, +0, -0, or -1 のいずれかを用いて行います。これらの票の大雑把な解釈は以下の通りです:

+1: "これはいい。強く同意します (I love the idea and I'm strongly committed to it.)"
+0: "いいんじゃないかな (Sounds OK to me.)"
-0: "あまりわくわくしないが、反対もしない (I'm not thrilled, but I won't stand in the way.)"
-1: "強く反対。このアイデアが実現したらとても嫌 (I strongly disagree and would be very unhappy to see the idea turn into reality.)"

django-developers での投票は正式なものではありませんが、その結果は真摯に受け止められます。適切な投票期間を経て、明らかな合意を形成できた場合には、投票の決定に従うでしょう。

とはいえ、つねに合意を形成できるわけではありません。その場合、完全コミッタ全員の中で十分に議論を重ねた後、最終判断を慈悲深き終身独裁者 (Benevolent Dictators for Life) である Adrian と Jacob に委ねることとします。

commit 権限¶

Django プロジェクトには二種類のコミッタがいます:

完全コミッタ (full committers)

長期間にわたって Django のコードベースに貢献してきており、メーリングリストにおいても礼儀正しく親切で、 Django の開発に十分な時間を割けることが分かっている人達です。

完全な commit 権限者の敷居は極めて高いものです。全ての完全コミッタによる全会一致でのみ受け入れることとし、その決定は覆りません。

部分コミッタ (partial committers)

「個別領域のエキスパート」です。管轄下にあるサブシステムのコードに直接チェックインする権限を持ち、サブシステムの懸案事項に対する正式な投票権を持ちます。このタイプの権限は、 Django の大きなサブフレームワークに貢献し、継続してメンテナンスを続けたい人に与えられるものです。

完全コミッタと同様、部分コミッタの受け入れも全ての完全コミッタ (と同じ領域の部分コミッタ) による全会一致でのみ受け入れることとします。とはいえ、敷居はやや低く、個別領域で十分な専門性を示しているということで十分です。

コミット権限を得たければ、現在コミッタを勤めているだれかに個人的にコンタクトしてください。コミット権限を公の場でリクエストするのはフレームの元であり、一切無視します。

Django v1.0 documentation

Django プロジェクトに協力するために¶

バグの報告¶

セキュリティ問題の報告¶

パッチの提出¶

チケットをクレーム（審査請求）する¶

チケットをクレームしたら¶

どのチケットをクレームすべきか¶

パッチ形式¶

重要パッチ¶

チケットのトリアージ¶

一般コミュニティメンバによるトリアージ¶

翻訳の提出と維持¶

コーディングスタイル¶

テンプレートのスタイル¶

ビューのスタイル¶

モデルのスタイル¶

ドキュメントの形式¶

新たな機能のドキュメント化¶

ReST ファイル作成のガイドライン¶

よく使う用語¶

Django 固有の用語¶

コードの commit¶

単体テストの作成¶

単体テストの実行¶

contrib アプリケーション¶

機能に関する要望¶

ブランチの管理ポリシ¶

ブランチを使う¶

Subversion からコードを取り出す¶

Python に別のバージョンの Django を使わせる¶

公式リリース¶

仕様に関する決定¶

commit 権限¶

Table Of Contents

前後のページ

現在のページ:

This Page

Quick search

Last update: