2008-08-24 06:25:40 +08:00
|
|
|
=============
|
|
|
|
|
API stability
|
|
|
|
|
=============
|
|
|
|
|
|
2015-06-20 20:58:10 +08:00
|
|
|
Django promises API stability and forwards-compatibility since version 1.0. In
|
|
|
|
|
a nutshell, this means that code you develop against a version of Django will
|
|
|
|
|
continue to work with future releases. You may need to make minor changes when
|
|
|
|
|
upgrading the version of Django your project uses: see the "Backwards
|
|
|
|
|
incompatible changes" section of the :doc:`release note </releases/index>` for
|
|
|
|
|
the version or versions to which you are upgrading.
|
2008-08-24 06:25:40 +08:00
|
|
|
|
|
|
|
|
What "stable" means
|
|
|
|
|
===================
|
|
|
|
|
|
|
|
|
|
In this context, stable means:
|
|
|
|
|
|
2013-02-20 07:19:50 +08:00
|
|
|
- All the public APIs (everything in this documentation) will not be moved
|
|
|
|
|
or renamed without providing backwards-compatible aliases.
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
- If new features are added to these APIs -- which is quite possible --
|
|
|
|
|
they will not break or change the meaning of existing methods. In other
|
|
|
|
|
words, "stable" does not (necessarily) mean "complete."
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
- If, for some reason, an API declared stable must be removed or replaced, it
|
|
|
|
|
will be declared deprecated but will remain in the API for at least two
|
2015-06-20 20:58:10 +08:00
|
|
|
feature releases. Warnings will be issued when the deprecated method is
|
|
|
|
|
called.
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
See :ref:`official-releases` for more details on how Django's version
|
|
|
|
|
numbering scheme works, and how features will be deprecated.
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
- We'll only break backwards compatibility of these APIs if a bug or
|
|
|
|
|
security hole makes it completely unavoidable.
|
2008-08-24 06:25:40 +08:00
|
|
|
|
|
|
|
|
Stable APIs
|
|
|
|
|
===========
|
|
|
|
|
|
2008-09-03 02:45:33 +08:00
|
|
|
In general, everything covered in the documentation -- with the exception of
|
2013-02-20 07:19:50 +08:00
|
|
|
anything in the :doc:`internals area </internals/index>` is considered stable.
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2008-09-03 02:45:33 +08:00
|
|
|
Exceptions
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
There are a few exceptions to this stability and backwards-compatibility
|
|
|
|
|
promise.
|
|
|
|
|
|
|
|
|
|
Security fixes
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
If we become aware of a security problem -- hopefully by someone following our
|
|
|
|
|
:ref:`security reporting policy <reporting-security-issues>` -- we'll do
|
2013-01-29 23:45:40 +08:00
|
|
|
everything necessary to fix it. This might mean breaking backwards
|
|
|
|
|
compatibility; security trumps the compatibility guarantee.
|
2008-09-03 02:45:33 +08:00
|
|
|
|
|
|
|
|
APIs marked as internal
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
Certain APIs are explicitly marked as "internal" in a couple of ways:
|
|
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
- Some documentation refers to internals and mentions them as such. If the
|
|
|
|
|
documentation says that something is internal, we reserve the right to
|
|
|
|
|
change it.
|
2010-11-01 08:52:58 +08:00
|
|
|
|
2011-10-14 08:12:01 +08:00
|
|
|
- Functions, methods, and other objects prefixed by a leading underscore
|
|
|
|
|
(``_``). This is the standard Python way of indicating that something is
|
|
|
|
|
private; if any method starts with a single ``_``, it's an internal API.
|
