Django is committed to API stability and forwards-compatibility. In a nutshell,\nthis means that code you develop against a version of Django will continue to\nwork with future releases. You may need to make minor changes when upgrading\nthe version of Django your project uses: see the “Backwards incompatible\nchanges” section of the release note for the version\nor versions to which you are upgrading.
\nAt the same time as making API stability a very high priority, Django is also\ncommitted to continual improvement, along with aiming for “one way to do it”\n(eventually) in the APIs we provide. This means that when we discover clearly\nsuperior ways to do things, we will deprecate and eventually remove the old\nways. Our aim is to provide a modern, dependable web framework of the highest\nquality that encourages best practices in all projects that use it. By using\nincremental improvements, we try to avoid both stagnation and large breaking\nupgrades.
\nIn this context, stable means:
\nAll the public APIs (everything in this documentation) will not be moved\nor renamed without providing backwards-compatible aliases.
If new features are added to these APIs – which is quite possible –\nthey will not break or change the meaning of existing methods. In other\nwords, “stable” does not (necessarily) mean “complete.”
If, for some reason, an API declared stable must be removed or replaced, it\nwill be declared deprecated but will remain in the API for at least two\nfeature releases. Warnings will be issued when the deprecated method is\ncalled.
\nSee Official releases for more details on how Django’s version\nnumbering scheme works, and how features will be deprecated.
\nWe’ll only break backwards compatibility of these APIs without a deprecation\nprocess if a bug or security hole makes it completely unavoidable.
In general, everything covered in the documentation – with the exception of\nanything in the internals area is considered stable.
\nThere are a few exceptions to this stability and backwards-compatibility\npromise.
\nIf we become aware of a security problem – hopefully by someone following our\nsecurity reporting policy – we’ll do\neverything necessary to fix it. This might mean breaking backwards\ncompatibility; security trumps the compatibility guarantee.
\nCertain APIs are explicitly marked as “internal” in a couple of ways:
\nSome documentation refers to internals and mentions them as such. If the\ndocumentation says that something is internal, we reserve the right to\nchange it.
Functions, methods, and other objects prefixed by a leading underscore\n(_). This is the standard Python way of indicating that something is\nprivate; if any method starts with a single _, it’s an internal API.