diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/misc/api-stability.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/parts/django/docs/misc/api-stability.txt Sat Jan 08 11:20:57 2011 +0530 @@ -0,0 +1,152 @@ +============= +API stability +============= + +:doc:`The release of Django 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 ` is considered stable as +of 1.0. This includes these APIs: + + - :doc:`Authorization ` + + - :doc:`Caching `. + + - :doc:`Model definition, managers, querying and transactions + ` + + - :doc:`Sending e-mail `. + + - :doc:`File handling and storage ` + + - :doc:`Forms ` + + - :doc:`HTTP request/response handling `, including file + uploads, middleware, sessions, URL resolution, view, and shortcut APIs. + + - :doc:`Generic views `. + + - :doc:`Internationalization `. + + - :doc:`Pagination ` + + - :doc:`Serialization ` + + - :doc:`Signals ` + + - :doc:`Templates `, including the language, Python-level + :doc:`template APIs `, and :doc:`custom template tags + and libraries `. 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 ` + + - :doc:`django-admin utility `. + + - :doc:`Built-in middleware ` + + - :doc:`Request/response objects `. + + - :doc:`Settings `. Note, though that while the :doc:`list of + built-in 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 `. Like settings, we'll probably add + new signals in the future, but the existing ones won't break. + + - :doc:`Unicode handling `. + + - Everything covered by the :doc:`HOWTO guides `. + +``django.utils`` +---------------- + +Most of the modules in ``django.utils`` are designed for internal use. Only +the following parts of :doc:`django.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 ` -- 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. +