PageRenderTime 12ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/docs/misc/api-stability.txt

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