From 5cef2cd4a10e51035e2728e3e5e59265bc0347e0 Mon Sep 17 00:00:00 2001 From: Luke Plant Date: Fri, 15 Nov 2019 22:06:33 +0300 Subject: [PATCH] Expanded API stability docs to include our policy of continual improvement. --- docs/misc/api-stability.txt | 25 +++++++++++++++++-------- 1 file 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 ` 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 ` 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 ===========