diff options
| author | Luke Plant <L.Plant.98@cantab.net> | 2019-11-15 22:06:33 +0300 |
|---|---|---|
| committer | Mariusz Felisiak <felisiak.mariusz@gmail.com> | 2019-11-18 20:37:46 +0100 |
| commit | 5cef2cd4a10e51035e2728e3e5e59265bc0347e0 (patch) | |
| tree | f44a8c6123d933bb7e356ac6163f67f99c30489e /docs | |
| parent | f95b59a1b3c7b24b4226bb81fc45248595b32263 (diff) | |
Expanded API stability docs to include our policy of continual improvement.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/misc/api-stability.txt | 25 |
1 files changed, 17 insertions, 8 deletions
diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index e18b3bb313..d59e557cc1 100644 --- a/docs/misc/api-stability.txt +++ b/docs/misc/api-stability.txt @@ -2,12 +2,21 @@ API stability ============= -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. +Django is committed to API stability and forwards-compatibility. 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. + +At the same time as making API stability a very high priority, Django is also +committed to continual improvement, along with aiming for "one way to do it" +(eventually) in the APIs we provide. This means that when we discover clearly +superior ways to do things, we will deprecate and eventually remove the old +ways. Our aim is to provide a modern, dependable web framework of the highest +quality that encourages best practices in all projects that use it. By using +incremental improvements, we try to avoid both stagnation and large breaking +upgrades. What "stable" means =================== @@ -29,8 +38,8 @@ In this context, stable means: See :ref:`official-releases` for more details on how Django's version numbering scheme works, and how features will be deprecated. -- We'll only break backwards compatibility of these APIs if a bug or - security hole makes it completely unavoidable. +- We'll only break backwards compatibility of these APIs without a deprecation + process if a bug or security hole makes it completely unavoidable. Stable APIs =========== |