Keseimbangan API¶
Django berkomitmen pada kestabilan API dan kesesuaian-kedepan. Dalam sebuah cangkang kacang, ini berarti bahwa kode anda kembangkan terhadap versi Django akan berlanjut bekerja dengan terbitan akan datang. Anda mungkin butuh membuat perubahan sedikit ketika meningkatkan versi dari Django proyek anda gunakan: lihat bagian "Backwards incompatible changes" dari release note untuk versi atau versi dimana anda meningkatkan.
Pada saat bersamaan ketika membuat kestabilan API prioritas sangat tinggi, Django juga berkomitmen melanjutkan peningkatan, bersama dengan tujuan untuk "satu cara melakukan itu" (akhirnya) dalam API kami sediakan. Ini berarti bahwa ketika mengungkapkan dengan jelas cara unggulan untuk melakukan ini, kami akan mengusangkan dan akhirnya menghilangkan cara lama. Tujuan kami adalah menyediakan kerangka kerja jaringan modern, bisa diandalkan dari kualitas tertinggi yang mencangkup praktik terbaik dalam semua proyek yang menggunakan itu. Dengan menggunakan peningkatan meningkat, kami mencoba menghindari kedua kebekuan dan kerusakan besar pada peningkatan.
Apa "stabil" berarti¶
Daam konteks ini, stabil berarti:
Semua API umum (semuanya di dokumentasi ini) tidak akan dipindahkan atau dinamai kembali tanpa menyediakan alias belakang-sesuai.
Jika fitur baru ini ditambahkan ke API ini -- yang sangat memungkinkan -- mereka akan tidak rusak atau merubah arti dari metode yang ada. Dengan kata lain, "stabil" tidak (perlu) berarti "lengkap."
Jika, untuk beberapa alasan, sebuah API dinyatakan stabil harus dipindahkan atau diganti, dia akan dinyatakan usang tetapi akan tetap berada di API unuk setidaknya dua fitur terbitan. Peringatan akan ditampilkan ketika metode pengusangan dipanggil.
Lihat Terbitan resmi untuk lebih rinci bagaimana skema penomoran versi Django bekerja, dan bagaimana fitur akan diusangkan.
Kami hanya akan memutuskan kesesuaian kebelakang dari APU berikut tanpa mengusangkan proses jika sebuah celah kesalahan atau keamanan membuatnya tidak dapat dihindari.
API Stabil¶
Pada umumnya, semaunya dicakupi di dokumentasi -- dengan pengecualian dari apapun di kawasan internal adalah dianggap stabil.
Pengecualian¶
Ada beberapa pengecualian pada kestabilan ini dan janji kecocokan-belakang.
Perbaikan keamanan¶
Jika kami menjadi waspada dari masalah keamanan -- semoga oleh seseorang mengikuti kebijakan pelaporan keamanan kami -- kami akan melakukan apapun yang dibutuhkan untuk memperbaikinya. Ini mungkin berarti merusak kecocokan sebelumnya; keamanan mengalahkan jaminan kecocokan.
API ditandai sebagai internal¶
Beberapa API secara eksplisit ditandai sebagai "internal" dalam sepsang jalan:
- Beberapa dokumentasi mengacu ke internal dan menyebutkan mereka seperti itu. Jika dokumentasi mengatakan sesuatu adalah internal, kami berhak untuk mengubahnya.
- Fungsi, metode, dan obyek lain diawali dengan dipimpin garis bawah (
_). Ini adalah standar cara Phyton dari mengindikasikan bahwa sesuatu adalah private; jika cara apapun mulai dengan_tunggal, itu adalah sebuah API internal.
