| 1 |
============= |
| 2 |
API stability |
| 3 |
============= |
| 4 |
|
| 5 |
Django is committed to API stability and forwards-compatibility. In a nutshell, |
| 6 |
this means that code you develop against a version of Django will continue to |
| 7 |
work with future releases. You may need to make minor changes when upgrading |
| 8 |
the version of Django your project uses: see the "Backwards incompatible |
| 9 |
changes" section of the :doc:`release note </releases/index>` for the version |
| 10 |
or versions to which you are upgrading. |
| 11 |
|
| 12 |
At the same time as making API stability a very high priority, Django is also |
| 13 |
committed to continual improvement, along with aiming for "one way to do it" |
| 14 |
(eventually) in the APIs we provide. This means that when we discover clearly |
| 15 |
superior ways to do things, we will deprecate and eventually remove the old |
| 16 |
ways. Our aim is to provide a modern, dependable web framework of the highest |
| 17 |
quality that encourages best practices in all projects that use it. By using |
| 18 |
incremental improvements, we try to avoid both stagnation and large breaking |
| 19 |
upgrades. |
| 20 |
|
| 21 |
What "stable" means |
| 22 |
=================== |
| 23 |
|
| 24 |
In this context, stable means: |
| 25 |
|
| 26 |
- All the public APIs (everything in this documentation) will not be moved |
| 27 |
or renamed without providing backwards-compatible aliases. |
| 28 |
|
| 29 |
- If new features are added to these APIs -- which is quite possible -- |
| 30 |
they will not break or change the meaning of existing methods. In other |
| 31 |
words, "stable" does not (necessarily) mean "complete." |
| 32 |
|
| 33 |
- If, for some reason, an API declared stable must be removed or replaced, it |
| 34 |
will be declared deprecated but will remain in the API for at least two |
| 35 |
feature releases. Warnings will be issued when the deprecated method is |
| 36 |
called. |
| 37 |
|
| 38 |
See :ref:`official-releases` for more details on how Django's version |
| 39 |
numbering scheme works, and how features will be deprecated. |
| 40 |
|
| 41 |
- We'll only break backwards compatibility of these APIs without a deprecation |
| 42 |
process if a bug or security hole makes it completely unavoidable. |
| 43 |
|
| 44 |
Stable APIs |
| 45 |
=========== |
| 46 |
|
| 47 |
In general, everything covered in the documentation -- with the exception of |
| 48 |
anything in the :doc:`internals area </internals/index>` is considered stable. |
| 49 |
|
| 50 |
Exceptions |
| 51 |
========== |
| 52 |
|
| 53 |
There are a few exceptions to this stability and backwards-compatibility |
| 54 |
promise. |
| 55 |
|
| 56 |
Security fixes |
| 57 |
-------------- |
| 58 |
|
| 59 |
If we become aware of a security problem -- hopefully by someone following our |
| 60 |
:ref:`security reporting policy <reporting-security-issues>` -- we'll do |
| 61 |
everything necessary to fix it. This might mean breaking backwards |
| 62 |
compatibility; security trumps the compatibility guarantee. |
| 63 |
|
| 64 |
APIs marked as internal |
| 65 |
----------------------- |
| 66 |
|
| 67 |
Certain APIs are explicitly marked as "internal" in a couple of ways: |
| 68 |
|
| 69 |
- Some documentation refers to internals and mentions them as such. If the |
| 70 |
documentation says that something is internal, we reserve the right to |
| 71 |
change it. |
| 72 |
|
| 73 |
- Functions, methods, and other objects prefixed by a leading underscore |
| 74 |
(``_``). This is the standard Python way of indicating that something is |
| 75 |
private; if any method starts with a single ``_``, it's an internal API. |