API の安定性¶
Django は API安定性と先方互換性に対して約束をしています。つまり、一度あるバージョンの Django で開発されたコードは将来の Django リリースでも動作し続けるということです。利用する Django のバージョンをアップグレードする場合は、小さな変更を加えなければいけない場合もあります: アップグレード前後のバージョンの リリースノート の "後方互換性のない変更" セクションを見てください。
API の安定性が非常に優先度が高いのと同時に、"one way to do it" (たった 1 つのやり方が(ゆくゆくは)あるはずだ) という目標に沿って、Django は絶え間無い改善についても約束しています。これは、何かを行う明快で非常に優れた方法を見付けたときに、古くなった方法を非推奨としゆくゆくは削除する、という意味です。我々の目標は、全てのプロジェクトが使うベストプラクティスを促進する最高品質の最新式で信頼できるウェブフレームワークを提供することです。漸進的に改善することで、足踏み状態とアップグレードの大幅なとぎれを避けようとしています。
"stable" とは？¶
現在の文脈では、stable とは次のことを意味します。
すべてのパブリック API (このドキュメントに書かれている全部です) は、基本的に移動や名称の変更が行われることがない。もし行われるとしても、後方互換性のためのエイリアスが必ず提供される。
もし新しい機能がこれらの API に追加されるなら (よくあることです)、すでに存在するメソッドの意味を変えたり、壊したりすることがない。別の言い方をすれば、"stable" とは必ずしも "complete" (完全) であることを意味するわけではない。
何からの理由により、一度 stable であると宣言された API を削除したり置き換えたりしなければならなくなった場合には、deprecated (廃止) であると明言され、最低でも2つのフィーチャーリリースの間は削除されずに残される。deprecated となったメソッドが呼び出されたときは、警告が出される。
Django のバージョンナンバリングのスキームの仕組みや、特定の機能の廃止されるプロセスについて詳しく知りたければ、 公式リリース を読んでください。
これらの API の後方互換性を非推奨プロセスなしで壊すのは、バグやセキュリティホールを修正するのにやむを得ない場合だけです。
stable な API¶
一般に、ドキュメントに書かれていることは、内部の仕組み の部分を除いて、すべて stable だと考えてもらって大丈夫です。
例外¶
安定性と後方互換性の保証について、数点だけ例外があります。
セキュリティ上の修正¶
もしセキュリティ上の問題に気がついた人がいたならば、セキュリティ問題報告ポリシー にしたがって報告するようにお願いします。速やかに必要な修正作業を行います。セキュリティは互換性の保証よりも優先されるため、やむを得ない場合には、後方互換性を壊すような修正が行われる可能性もあります。
internal と記された API¶
特定の API は、次のような方法で、明示的に "internal" (内部実装) と明記されています。
ドキュメントの中には内部実装を参照していたり、内部実装であると述べている箇所があります。もし、ドキュメントが「これは内部実装である」と述べている場合、その箇所は変更される場合があります。
先頭にアンダースコア(
_)が付いた関数、メソッド、およびその他のオブジェクトは、プライベートなものであることを示すPythonの標準的な方法です。 いずれかのメソッドが単一の_で始まる場合、それは内部APIです。
