API stability

The release of Django 1.0附带了API稳定性和向前兼容性的承诺。简而言之，这意味着，针对1.X版本的Django开发的代码将继续适用于未来的1.X版本。您可能需要在升级项目使用的Django版本时进行小幅更改：有关要升级的版本，请参阅release note的“向后不兼容的更改”部分。

What “stable” means

在这种情况下，稳定意味着：

  • 所有公共API（本文档中的所有内容）将不会被移动或重命名，而不提供向后兼容的别名。

  • 如果向这些API添加新功能（这是很有可能的），它们不会破坏或更改现有方法的含义。换句话说，“稳定”不一定意味着“完全”。

  • 如果由于某些原因，必须删除或替换已声明为稳定的API，那么它将被声明为已弃用，但会保留在API中至少有两个次要版本。当调用已弃用的方法时将发出警告。

    有关Django的版本编号方案如何工作以及如何弃用功能的详细信息，请参见Official releases。

  • 如果一个错误或安全漏洞使得这些API完全不可避免，我们只会破坏这些API的向后兼容性。

Stable APIs

一般来说，文档中涵盖的一切 - 除了internals area中的任何内容都被视为稳定。

Exceptions

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

Security fixes

如果我们发现有安全问题（希望有人按照我们的security reporting policy），我们会尽一切必要措施予以解决。这可能意味着破坏向后兼容性；安全胜过兼容性保证。

APIs marked as internal

某些API通过以下几种方式显式标记为“内部”：

  • 一些文档提到内部并提到它们。如果文档说明内容是内部的，我们保留更改它的权利。
  • 函数，方法和其他以前导下划线（_）为前缀的对象。这是标准的Python方式，表明某事是私有的；如果任何方法从单个_开始，它是一个内部API。