API stability

Django承诺自版本1.0以来的API稳定性和转发兼容性。 简而言之,这意味着您针对Django版本开发的代码将继续适用于未来版本。 您可能需要在升级项目使用的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。