| ============= |
| API stability |
| ============= |
| |
| :doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API |
| stability and forwards-compatibility. In a nutshell, this means that code you |
| develop against a 1.X version of Django will continue to work with future |
| 1.X 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 :doc:`release note </releases/index>` for the version or versions to which |
| you are upgrading. |
| |
| What "stable" means |
| =================== |
| |
| In this context, stable means: |
| |
| - All the public APIs (everything in this documentation) will not be moved |
| or renamed without providing backwards-compatible aliases. |
| |
| - If new features are added to these APIs -- which is quite possible -- |
| they will not break or change the meaning of existing methods. In other |
| words, "stable" does not (necessarily) mean "complete." |
| |
| - If, for some reason, an API declared stable must be removed or replaced, it |
| will be declared deprecated but will remain in the API for at least two |
| minor version releases. Warnings will be issued when the deprecated method |
| is called. |
| |
| See :ref:`official-releases` for more details on how Django's version |
| numbering scheme works, and how features will be deprecated. |
| |
| - We'll only break backwards compatibility of these APIs if a bug or |
| security hole makes it completely unavoidable. |
| |
| Stable APIs |
| =========== |
| |
| In general, everything covered in the documentation -- with the exception of |
| anything in the :doc:`internals area </internals/index>` is considered stable. |
| |
| Exceptions |
| ========== |
| |
| There are a few exceptions to this stability and backwards-compatibility |
| promise. |
| |
| Security fixes |
| -------------- |
| |
| If we become aware of a security problem -- hopefully by someone following our |
| :ref:`security reporting policy <reporting-security-issues>` -- we'll do |
| everything necessary to fix it. This might mean breaking backwards |
| compatibility; security trumps the compatibility guarantee. |
| |
| APIs marked as internal |
| ----------------------- |
| |
| Certain APIs are explicitly marked as "internal" in a couple of ways: |
| |
| - Some documentation refers to internals and mentions them as such. If the |
| documentation says that something is internal, we reserve the right to |
| change it. |
| |
| - Functions, methods, and other objects prefixed by a leading underscore |
| (``_``). This is the standard Python way of indicating that something is |
| private; if any method starts with a single ``_``, it's an internal API. |
| |
| .. _misc-api-stability-localflavor: |
| |
| Local flavors |
| ------------- |
| |
| .. versionchanged:: 1.3 |
| |
| :mod:`django.contrib.localflavor` contains assorted pieces of code |
| that are useful for particular countries or cultures. This data is |
| local in nature, and is subject to change on timelines that will |
| almost never correlate with Django's own release schedules. For |
| example, a common change is to split a province into two new |
| provinces, or to rename an existing province. |
| |
| These changes present two competing compatibility issues. Moving |
| forward, displaying the names of deprecated, renamed and dissolved |
| provinces in a selection widget is bad from a user interface |
| perspective. However, maintaining full backwards compatibility |
| requires that we support historical values that may be stored in a |
| database -- including values that may no longer be valid. |
| |
| Therefore, Django has the following policy with respect to changes in |
| local flavor: |
| |
| * At the time of a Django release, the data and algorithms |
| contained in :mod:`django.contrib.localflavor` will, to the best |
| of our ability, reflect the officially gazetted policies of the |
| appropriate local government authority. If a province has been |
| added, altered, or removed, that change will be reflected in |
| Django's localflavor. |
| |
| * These changes will *not* be backported to the previous stable |
| release. Upgrading a minor version of Django should not require |
| any data migration or audits for UI changes; therefore, if you |
| want to get the latest province list, you will either need to |
| upgrade your Django install, or backport the province list you |
| need. |
| |
| * For one release, the affected localflavor module will raise a |
| ``RuntimeWarning`` when it is imported. |
| |
| * The change will be announced in the release notes as a backwards |
| incompatible change requiring attention. The change will also be |
| annotated in the documentation for the localflavor module. |
| |
| * Where necessary and feasible, a migration script will be provided |
| to aid the migration process. |
| |
| For example, Django 1.2 contains an Indonesian localflavor. It has a |
| province list that includes "Nanggroe Aceh Darussalam (NAD)" as a |
| province. The Indonesian government has changed the official name of |
| the province to "Aceh (ACE)". As a result, Django 1.3 does *not* |
| contain "Nanggroe Aceh Darussalam (NAD)" in the province list, but |
| *does* contain "Aceh (ACE)". |