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 21:40:22 +0100 |
| commit | da186625a017175e9caccc304474511620d4c6ef (patch) | |
| tree | 791cace40fc878081d06c2c1e499c3884345a579 | |
| parent | d5e8ad004913bc5aa9925b997154d5ef8bcb81cd (diff) | |
| download | django-da186625a017175e9caccc304474511620d4c6ef.tar.gz | |
[2.2.x] Expanded API stability docs to include our policy of continual improvement.
Backport of 5cef2cd4a10e51035e2728e3e5e59265bc0347e0 from master
| -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 =========== |