PageRenderTime 36ms CodeModel.GetById 17ms RepoModel.GetById 1ms app.codeStats 0ms

Plain Text | 206 lines | 148 code | 58 blank | 0 comment | 0 complexity | 6493ad581cb72fe5cf22481217fe0795 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. =============
  2. API stability
  3. =============
  4. :doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
  5. stability and forwards-compatibility. In a nutshell, this means that code you
  6. develop against Django 1.0 will continue to work against 1.1 unchanged, and you
  7. should need to make only minor changes for any 1.X release.
  8. What "stable" means
  9. ===================
  10. In this context, stable means:
  11. - All the public APIs -- everything documented in the linked documents below,
  12. and all methods that don't begin with an underscore -- will not be moved or
  13. renamed without providing backwards-compatible aliases.
  14. - If new features are added to these APIs -- which is quite possible --
  15. they will not break or change the meaning of existing methods. In other
  16. words, "stable" does not (necessarily) mean "complete."
  17. - If, for some reason, an API declared stable must be removed or replaced, it
  18. will be declared deprecated but will remain in the API for at least two
  19. minor version releases. Warnings will be issued when the deprecated method
  20. is called.
  21. See :ref:`official-releases` for more details on how Django's version
  22. numbering scheme works, and how features will be deprecated.
  23. - We'll only break backwards compatibility of these APIs if a bug or
  24. security hole makes it completely unavoidable.
  25. Stable APIs
  26. ===========
  27. In general, everything covered in the documentation -- with the exception of
  28. anything in the :doc:`internals area </internals/index>` is considered stable as
  29. of 1.0. This includes these APIs:
  30. - :doc:`Authorization </topics/auth>`
  31. - :doc:`Caching </topics/cache>`.
  32. - :doc:`Model definition, managers, querying and transactions
  33. </topics/db/index>`
  34. - :doc:`Sending e-mail </topics/email>`.
  35. - :doc:`File handling and storage </topics/files>`
  36. - :doc:`Forms </topics/forms/index>`
  37. - :doc:`HTTP request/response handling </topics/http/index>`, including file
  38. uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
  39. - :doc:`Generic views </topics/http/generic-views>`.
  40. - :doc:`Internationalization </topics/i18n/index>`.
  41. - :doc:`Pagination </topics/pagination>`
  42. - :doc:`Serialization </topics/serialization>`
  43. - :doc:`Signals </topics/signals>`
  44. - :doc:`Templates </topics/templates>`, including the language, Python-level
  45. :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags
  46. and libraries </howto/custom-template-tags>`. We may add new template
  47. tags in the future and the names may inadvertently clash with
  48. external template tags. Before adding any such tags, we'll ensure that
  49. Django raises an error if it tries to load tags with duplicate names.
  50. - :doc:`Testing </topics/testing>`
  51. - :doc:`django-admin utility </ref/django-admin>`.
  52. - :doc:`Built-in middleware </ref/middleware>`
  53. - :doc:`Request/response objects </ref/request-response>`.
  54. - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of
  55. built-in settings </ref/settings>` can be considered complete we may -- and
  56. probably will -- add new settings in future versions. This is one of those
  57. places where "'stable' does not mean 'complete.'"
  58. - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add
  59. new signals in the future, but the existing ones won't break.
  60. - :doc:`Unicode handling </ref/unicode>`.
  61. - Everything covered by the :doc:`HOWTO guides </howto/index>`.
  62. ``django.utils``
  63. ----------------
  64. Most of the modules in ``django.utils`` are designed for internal use. Only
  65. the following parts of :doc:`django.utils </ref/utils>` can be considered stable:
  66. - ``django.utils.cache``
  67. - ``django.utils.datastructures.SortedDict`` -- only this single class; the
  68. rest of the module is for internal use.
  69. - ``django.utils.encoding``
  70. - ``django.utils.feedgenerator``
  71. - ``django.utils.http``
  72. - ``django.utils.safestring``
  73. - ``django.utils.translation``
  74. - ``django.utils.tzinfo``
  75. Exceptions
  76. ==========
  77. There are a few exceptions to this stability and backwards-compatibility
  78. promise.
  79. Security fixes
  80. --------------
  81. If we become aware of a security problem -- hopefully by someone following our
  82. :ref:`security reporting policy <reporting-security-issues>` -- we'll do
  83. everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee.
  84. Contributed applications (``django.contrib``)
  85. ---------------------------------------------
  86. While we'll make every effort to keep these APIs stable -- and have no plans to
  87. break any contrib apps -- this is an area that will have more flux between
  88. releases. As the Web evolves, Django must evolve with it.
  89. However, any changes to contrib apps will come with an important guarantee:
  90. we'll make sure it's always possible to use an older version of a contrib app if
  91. we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible
  92. ``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
  93. version alongside Django 1.5. This will continue to allow for easy upgrades.
  94. Historically, apps in ``django.contrib`` have been more stable than the core, so
  95. in practice we probably won't have to ever make this exception. However, it's
  96. worth noting if you're building apps that depend on ``django.contrib``.
  97. APIs marked as internal
  98. -----------------------
  99. Certain APIs are explicitly marked as "internal" in a couple of ways:
  100. - Some documentation refers to internals and mentions them as such. If the
  101. documentation says that something is internal, we reserve the right to
  102. change it.
  103. - Functions, methods, and other objects prefixed by a leading underscore
  104. (``_``). This is the standard Python way of indicating that something is
  105. private; if any method starts with a single ``_``, it's an internal API.
  106. .. _misc-api-stability-localflavor:
  107. Local flavors
  108. -------------
  109. .. versionchanged:: 1.3
  110. :mod:`django.contrib.localflavor` contains assorted pieces of code
  111. that are useful for particular countries or cultures. This data is
  112. local in nature, and is subject to change on timelines that will
  113. almost never correlate with Django's own release schedules. For
  114. example, a common change is to split a province into two new
  115. provinces, or to rename an existing province.
  116. These changes present two competing compatibility issues. Moving
  117. forward, displaying the names of deprecated, renamed and dissolved
  118. provinces in a selection widget is bad from a user interface
  119. perspective. However, maintaining full backwards compatibility
  120. requires that we support historical values that may be stored in a
  121. database -- including values that may no longer be valid.
  122. Therefore, Django has the following policy with respect to changes in
  123. local flavor:
  124. * At the time of a Django release, the data and algorithms
  125. contained in :mod:`django.contrib.localflavor` will, to the best
  126. of our ability, reflect the officially gazetted policies of the
  127. appropriate local government authority. If a province has been
  128. added, altered, or removed, that change will be reflected in
  129. Django's localflavor.
  130. * These changes will *not* be backported to the previous stable
  131. release. Upgrading a minor version of Django should not require
  132. any data migration or audits for UI changes; therefore, if you
  133. want to get the latest province list, you will either need to
  134. upgrade your Django install, or backport the province list you
  135. need.
  136. * For one release, the affected localflavor module will raise a
  137. ``RuntimeWarning`` when it is imported.
  138. * The change will be announced in the release notes as a backwards
  139. incompatible change requiring attention. The change will also be
  140. annotated in the documentation for the localflavor module.
  141. * Where necessary and feasible, a migration script will be provided
  142. to aid the migration process.
  143. For example, Django 1.2 contains an Indonesian localflavor. It has a
  144. province list that includes "Nanggroe Aceh Darussalam (NAD)" as a
  145. province. The Indonesian government has changed the official name of
  146. the province to "Aceh (ACE)". As a result, Django 1.3 does *not*
  147. contain "Nanggroe Aceh Darussalam (NAD)" in the province list, but
  148. *does* contain "Aceh (ACE)".