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

revision-up-to:11321 (1.1) unfinished

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 コマンドの返す書式のパッチを提出してください。ただし、コー ドよりも英語で変更点を説明した方がはるかに分かりやすい場合は例外です。 例えばインデントはよくある例です。というのも、コードの違いがインデン トでしかない場合、パッチを読むのはとても大変だからです。

    git diff 形式のパッチでもかまいません。

  • パッチを作るときには、 常に trunk ディレクトリの最上位の階層、 すなわち、 django, docs, tests, AUTHORS などがある場 所で svn diff を実行してください。こうしてパッチを作ったほうが 他の人が適用しやすいからです。

  • チケットトラッカ で、 “attach file” ボタンを使ってチケットにパッチ を添付してください。一行のパッチでないかぎり、チケットの説明やコメン トの中にパッチを 入れないで 下さい。

  • パッチファイルの名前には .diff 拡張子をつけて下さい。そうすること で、チケットトラッカは構文のハイライト強調を正しく行うので助かります。

  • チケットの詳細情報欄にある「パッチ付き」(“Has patch”) ボックスにチェッ クを入れてください。チケットがパッチつきであることが分かりやすくなり、 チケットシステムがそのチケットを パッチつきのチケットのリスト に追 加してくれます。

  • 問題を解決したり機能を追加するためのコードはパッチの重要な部分ですが、 それだけではいけません。よいパッチというものには必ず回帰テストが付属 していて、問題が解決されたことを検証できる (そして将来同様の問題が再 発しないようにできる) ものです。

  • パッチ中のコードが新たな機能や既存の機能に対する変更をもたらす場合、 パッチにはドキュメントも含めてください。

要注意パッチ

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

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

チケットのトリアージ

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

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

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

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

Django のチケットワークフロー図

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

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

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

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

新たな機能のドキュメントを書くには

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

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

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

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

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

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

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

Django のドキュメントシステム のページには、 詳しい情報が書かれています。ドキュメントを書き始めるまえに、必ず一読してく ださい。

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

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

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

よく使う用語

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

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

Django 固有の用語

  • model – 頭文字は小文字です。
  • template – 頭文字は小文字です。
  • URLconf – “URL” は大文字、 “conf” は小文字です。
  • view – 頭文字は小文字です。

コードのコミット

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 のコア開発者全員が変更を追うための 大きな 助けになります。

  • バグフィクスと機能の改善とを分離してください。

    バグフィクスは現在のバグフィクスブランチ (1.0.X ブランチなど) と、 現在の trunk の両方に施す必要があるからです。

  • コミットによって 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 だけです。

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

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

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

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

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

memcached キャッシュバックエンドをテストしたければ、 CACHE_BACKEND 設定に memcached インスタンスを定義しておかねばな りません。

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

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

例えば、 Django が PYTHONPATH 上になく、 settings.pytests/ ディレクトリにある場合で、汎用リレーション (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 は実際の開発者が実際の仕事に使うために設計されている ので、ある機能がどのようにユーザの役に立つのかを説明する必要がありま す。

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

ブランチの管理ポリシ

一般的に、Django の trunk は安定に保たれています。誰がいつ trunk から取り出 したDjango でも、実運用のサイトを走らせられるはずです。さらに、私たちは、 trunk への変更は可能なかぎりアトミックに行われるべきで、より細かい単位の変 更がベターだと考えています。従って、大掛かりな変更、すなわち一つのパッチに 収まらないくらい大きな変更を伴う合や、多くの人が関わる必要のある変更の場合 には、専用のブランチを作成します。

つまり、一つのパッチで済まないような大きな機能や、大掛かりなリファクタリ ングは機能ブランチ (feature branch) で行わねばならないのです。私たちの開発 プロセスです、機能ブランチのありかたに、二つの選択肢をもたせています:

  1. GitMercurial, Bazaar といった分散リビジョンコントロールシステ

    ムを使った機能ブランチ。

    If you’re familiar with one of these tools, this is probably your best option since it doesn’t require any support or buy-in from the Django core developers.

    However, do keep in mind that Django will continue to use Subversion for the foreseeable future, and this will naturally limit the recognition of your branch. Further, if your branch becomes eligible for merging to trunk you’ll need to find a core developer familiar with your DVCS of choice who’ll actually perform the merge.

    If you do decided to start a distributed branch of Django and choose to make it public, please add the branch to the Django branches wiki page.

  2. Feature branches using SVN have a higher bar. If you want a branch in SVN itself, you’ll need a “mentor” among the core committers. This person is responsible for actually creating the branch, monitoring your process (see below), and ultimately merging the branch into trunk.

    If you want a feature branch in SVN, you’ll need to ask in django-developers for a mentor.

Branch rules

We’ve got a few rules for branches born out of experience with what makes a successful Django branch.

DVCS branches are obviously not under central control, so we have no way of enforcing these rules. However, if you’re using a DVCS, following these rules will give you the best chance of having a successful branch (read: merged back to trunk).

Developers with branches in SVN, however, must follow these rules. The branch mentor will keep on eye on the branch and will delete it if these rules are broken.

  • Only branch entire copies of the Django tree, even if work is only happening on part of that tree. This makes it painless to switch to a branch.

  • Merge changes from trunk no less than once a week, and preferably every couple-three days.

    In our experience, doing regular trunk merges is often the difference between a successful branch and one that fizzles and dies.

    If you’re working on an SVN branch, you should be using svnmerge.py to track merges from trunk.

  • Keep tests passing and documentation up-to-date. As with patches, we’ll only merge a branch that comes with tests and documentation.

Once the branch is stable and ready to be merged into the trunk, alert 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-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 に委ねます。

コミット権限

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

完全コミッタ (full committers)

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

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

部分コミッタ (partial committers)

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

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

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