diff options
Diffstat (limited to 'parts/django/docs/misc/api-stability.txt')
| -rw-r--r-- | parts/django/docs/misc/api-stability.txt | 152 |
1 files changed, 0 insertions, 152 deletions
diff --git a/parts/django/docs/misc/api-stability.txt b/parts/django/docs/misc/api-stability.txt deleted file mode 100644 index 456d84b..0000000 --- a/parts/django/docs/misc/api-stability.txt +++ /dev/null @@ -1,152 +0,0 @@ -============= -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 Django 1.0 will continue to work against 1.1 unchanged, and you -should need to make only minor changes for any 1.X release. - -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. - - - 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 as -of 1.0. This includes these APIs: - - - :doc:`Authorization </topics/auth>` - - - :doc:`Caching </topics/cache>`. - - - :doc:`Model definition, managers, querying and transactions - </topics/db/index>` - - - :doc:`Sending e-mail </topics/email>`. - - - :doc:`File handling and storage </topics/files>` - - - :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:`Generic views </topics/http/generic-views>`. - - - :doc:`Internationalization </topics/i18n/index>`. - - - :doc:`Pagination </topics/pagination>` - - - :doc:`Serialization </topics/serialization>` - - - :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:`Testing </topics/testing>` - - - :doc:`django-admin utility </ref/django-admin>`. - - - :doc:`Built-in middleware </ref/middleware>` - - - :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:`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>`. - - - Everything covered by the :doc:`HOWTO guides </howto/index>`. - -``django.utils`` ----------------- - -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`` - -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. - -Contributed applications (``django.contrib``) ---------------------------------------------- - -While we'll make every effort to keep these APIs stable -- and have no plans to -break any contrib apps -- this is an area that will have more flux between -releases. As the Web evolves, Django must evolve with it. - -However, any changes to contrib apps will come with an important guarantee: -we'll make sure it's always possible to use an older version of a contrib app if -we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible -``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4 -version alongside Django 1.5. This will continue to allow for easy upgrades. - -Historically, apps in ``django.contrib`` have been more stable than the core, so -in practice we probably won't have to ever make this exception. However, it's -worth noting if you're building apps that depend on ``django.contrib``. - -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. - |