diff options
Diffstat (limited to 'docs/misc/api-stability.txt')
| -rw-r--r-- | docs/misc/api-stability.txt | 168 |
1 files changed, 84 insertions, 84 deletions
diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index 3ff563dc67..75fa6b4418 100644 --- a/docs/misc/api-stability.txt +++ b/docs/misc/api-stability.txt @@ -12,24 +12,24 @@ What "stable" means In this context, stable means: - - All the public APIs -- everything documented in the linked documents below, - and all methods that don't begin with an underscore -- will not be moved or - renamed without providing backwards-compatible aliases. +- All the public APIs -- everything documented in the linked documents below, + and all methods that don't begin with an underscore -- 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 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. +- 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. + 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. +- We'll only break backwards compatibility of these APIs if a bug or + security hole makes it completely unavoidable. Stable APIs =========== @@ -38,58 +38,58 @@ In general, everything covered in the documentation -- with the exception of anything in the :doc:`internals area </internals/index>` is considered stable as of 1.0. This includes these APIs: - - :doc:`Authorization </topics/auth>` +- :doc:`Authorization </topics/auth>` - - :doc:`Caching </topics/cache>`. +- :doc:`Caching </topics/cache>`. - - :doc:`Model definition, managers, querying and transactions - </topics/db/index>` +- :doc:`Model definition, managers, querying and transactions + </topics/db/index>` - - :doc:`Sending email </topics/email>`. +- :doc:`Sending email </topics/email>`. - - :doc:`File handling and storage </topics/files>` +- :doc:`File handling and storage </topics/files>` - - :doc:`Forms </topics/forms/index>` +- :doc:`Forms </topics/forms/index>` - - :doc:`HTTP request/response handling </topics/http/index>`, including file - uploads, middleware, sessions, URL resolution, view, and shortcut APIs. +- :doc:`HTTP request/response handling </topics/http/index>`, including file + uploads, middleware, sessions, URL resolution, view, and shortcut APIs. - - :doc:`Generic views </topics/http/generic-views>`. +- :doc:`Generic views </topics/http/generic-views>`. - - :doc:`Internationalization </topics/i18n/index>`. +- :doc:`Internationalization </topics/i18n/index>`. - - :doc:`Pagination </topics/pagination>` +- :doc:`Pagination </topics/pagination>` - - :doc:`Serialization </topics/serialization>` +- :doc:`Serialization </topics/serialization>` - - :doc:`Signals </topics/signals>` +- :doc:`Signals </topics/signals>` - - :doc:`Templates </topics/templates>`, including the language, Python-level - :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags - and libraries </howto/custom-template-tags>`. We may add new template - tags in the future and the names may inadvertently clash with - external template tags. Before adding any such tags, we'll ensure that - Django raises an error if it tries to load tags with duplicate names. +- :doc:`Templates </topics/templates>`, including the language, Python-level + :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags + and libraries </howto/custom-template-tags>`. We may add new template + tags in the future and the names may inadvertently clash with + external template tags. Before adding any such tags, we'll ensure that + Django raises an error if it tries to load tags with duplicate names. - - :doc:`Testing </topics/testing>` +- :doc:`Testing </topics/testing>` - - :doc:`django-admin utility </ref/django-admin>`. +- :doc:`django-admin utility </ref/django-admin>`. - - :doc:`Built-in middleware </ref/middleware>` +- :doc:`Built-in middleware </ref/middleware>` - - :doc:`Request/response objects </ref/request-response>`. +- :doc:`Request/response objects </ref/request-response>`. - - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of - built-in settings </ref/settings>` can be considered complete we may -- and - probably will -- add new settings in future versions. This is one of those - places where "'stable' does not mean 'complete.'" +- :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of + built-in settings </ref/settings>` can be considered complete we may -- and + probably will -- add new settings in future versions. This is one of those + places where "'stable' does not mean 'complete.'" - - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add - new signals in the future, but the existing ones won't break. +- :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add + new signals in the future, but the existing ones won't break. - - :doc:`Unicode handling </ref/unicode>`. +- :doc:`Unicode handling </ref/unicode>`. - - Everything covered by the :doc:`HOWTO guides </howto/index>`. +- Everything covered by the :doc:`HOWTO guides </howto/index>`. ``django.utils`` ---------------- @@ -97,15 +97,15 @@ of 1.0. This includes these APIs: Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of :doc:`django.utils </ref/utils>` can be considered stable: - - ``django.utils.cache`` - - ``django.utils.datastructures.SortedDict`` -- only this single class; the - rest of the module is for internal use. - - ``django.utils.encoding`` - - ``django.utils.feedgenerator`` - - ``django.utils.http`` - - ``django.utils.safestring`` - - ``django.utils.translation`` - - ``django.utils.tzinfo`` +- ``django.utils.cache`` +- ``django.utils.datastructures.SortedDict`` -- only this single class; the + rest of the module is for internal use. +- ``django.utils.encoding`` +- ``django.utils.feedgenerator`` +- ``django.utils.http`` +- ``django.utils.safestring`` +- ``django.utils.translation`` +- ``django.utils.tzinfo`` Exceptions ========== @@ -142,13 +142,13 @@ 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. +- 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. +- 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: @@ -174,29 +174,29 @@ 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. +* 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 |