API 的稳定性

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 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.

什么是“稳定性”？

在此处，稳定意味着：

• 所有发布的 API （在文档中的一切 API ）在不提供向后兼容的别名的情况下，都不会被移除或者重命名。

• 如果文档中的 API 添加了新特性（这是极有可能的），新特性不会导致现有方法罢工或者修改方法的含义。也就是说，“稳定性”并不意味着“不变性”。

• 假如因为某些原因，一个“稳定的” API 必须被移除或者被代替，它将会被弃用但仍然会被保留直到至少有两个新特性发布。当调用即将被弃用的方法时，会产生警告。

  有关 Django 是如何编写版本号以及一些功能是如何被弃用的详细信息，请看： Official releases。

• We'll only break backwards compatibility of these APIs without a deprecation process if a bug or security hole makes it completely unavoidable.

稳定的 API

一般来说，文档中的一切都确定是稳定的，除开 internals area。

例外

这种稳定性和向后兼容性承诺有一些例外。

安全修复

如果我们发现了安全问题 --希望报告者遵照我们的 安全报告政策--我们会尽一切努力解决它。 这可能意味着打破向后兼容性; 安全性优先于兼容性保证。

标记为内部的 API

某些API在几种方式中被明确标记为 "内部" :

• 一些文档提及了这些 API 并标为“内部”，如果确实如此，我们保留修改它的权利。
• 一些函数，方法以及其他对象以下划线“_”开头，这是 Python 声明其为“私有”的标准方式，如果一个方法以单下划线“_”开头，那么这意味着它是 Django 内部的一个 API。