| revision-up-to: | 8961 (1.0) |
|---|
Django 1.0 のリリース によって、 API の安定性と互換性 に一定の保証が与えられました。これはつまり、 Django 1.0 用に書いたコードは 何も変更せずに 1.1 でも動作し、以後の 1.X リリースではほんのわずかな変更し か必要ないということです。
ここでいう「安定」とは、以下のような意味です:
公開 API – リンクからたどれるドキュメント内で開設されていて、メソッド 名がアンダースコアで始まらないもの – の配置や名前を変更する場合には、 以前のバージョンとの互換性のための別名のメソッドを提供します。
API に新たな機能を追加する場合 – これはよくあることですが – でも、 既存のメソッドの意味を無くしたり、変えたりすることはありません。換言す れば、「安定」していても (必ずしも) 「完全」ではない、ということです。
すでに安定と宣言されている API を何らかの理由で削除したり移動したりせ ねばならない場合、それらのメソッドは撤廃 (deprecated) とみなされ、少な くとも二つのマイナーバージョン変更までは API 中に残します。撤廃された メソッドを呼び出した場合には警告メッセージを表示します。
Django のバージョン番号の定義と、どの機能が撤廃されているかは、 公式リリース を参照してください。
深刻なバグやセキュリティホールによってやむを得ない場合に限り、これらの API に対して互換性のない変更を行います。
全般的に、 内部仕様 の中にあるドキュメントを除き、 ドキュメント中でカバーされている機能は、 1.0 の時点で安定な API と考えてか まいません。安定な API を以下に示します:
安定性や互換性の維持には、いくつか例外を設けています。
セキュリティ上の問題を認識した (理想的には セキュリティレポートのポリシ に基づいて 報告された) 場合、必要な修正を行います。その結果、互換性が失われる可能性が あります。セキュリティ上の問題の解決は、互換性の保証よりも優先です。
While we’ll make every effort to keep these APIs stable – and have no plans to break any contrib apps – this is an area that will have more flux between releases. As the web evolves, Django must evolve with it.
However, any changes to contrib apps will come with an important guarantee: we’ll make sure it’s always possible to use an older version of a contrib app if we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible django.contrib.flatpages, we’ll make sure you can still use the Django 1.4 version alongside Django 1.5. This will continue to allow for easy upgrades.
Historically, apps in django.contrib have been more stable than the core, so in practice we probably won’t have to ever make this exception. However, it’s worth noting if you’re building apps that depend on django.contrib.
API の中には、以下の二つの理由から「内部使用 (internal)」とマークされている ものがあります:
Aug 31, 2012