diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index 0e60990542..cb2c3ac804 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -935,6 +935,8 @@ file. Then copy the branch's version of the ``django`` directory into .. _path file: http://docs.python.org/lib/module-site.html +.. _official-releases: + Official releases ================= diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index 0bf4b984c4..f5dc5fa98f 100644 --- a/docs/misc/api-stability.txt +++ b/docs/misc/api-stability.txt @@ -4,27 +4,31 @@ API stability ============= -Although Django has not reached a 1.0 release, the bulk of Django's public APIs are -stable as of the 0.95 release. This document explains which APIs will and will not -change before the 1.0 release. +:ref:`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, and - all methods that don't begin with an underscore -- will not be moved or + - 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 until at least - version 1.1. Warnings will be issued when the deprecated method is - called. + 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. @@ -32,64 +36,114 @@ In this context, stable means: Stable APIs =========== -These APIs are stable: +In general, everything covered in the documentation -- with the exception of +anything in the :ref:`internals area ` is considered stable as +of 1.0. This includes these APIs: - - :ref:`Caching `. - - - :ref:`Custom template tags and libraries `. - - - :ref:`Database lookup ` (with the exception of validation; see below). + - :ref:`Authorization ` + + - :ref:`Caching `. - - :ref:`django-admin utility `. - - - :ref:`FastCGI and mod_python integration `. - - - :ref:`Flatpages `. - - - :ref:`Generic views `. - - - :ref:`Internationalization `. - - - :ref:`Legacy database integration `. - - - :ref:`Model definition ` (with the exception of generic relations; see below). + - :ref:`Model definition, managers, querying and transactions + ` + + - :ref:`Sending e-mail `. + + - :ref:`File handling and storage ` + + - :ref:`Forms ` + + - :ref:`HTTP request/response handling `, including file + uploads, middleware, sessions, URL resolution, view, and shortcut APIs. + + - :ref:`Generic views `. + + - :ref:`Internationalization `. + + - :ref:`Pagination ` + + - :ref:`Serialization ` + + - :ref:`Signals ` + + - :ref:`Templates `, including the language, Python-level + :ref:`template APIs `, and :ref:`custom template tags + and libraries `. - - :ref:`Redirects `. - - - :ref:`Request/response objects `. - - - :ref:`Sending e-mail `. - - - :ref:`Sessions `. - - - :ref:`Settings `. - - - :ref:`Syndication `. - - - :ref:`Template language ` (with the exception of some - possible disambiguation of how tag arguments are passed to tags and - filters). - - - :ref:`Transactions `. - - - :ref:`URL dispatch `. - -You'll notice that this list comprises the bulk of Django's APIs. That's right --- most of the changes planned between now and Django 1.0 are either under the -hood, feature additions, or changes to a few select bits. A good estimate is -that 90% of Django can be considered forwards-compatible at this point. + - :ref:`Testing ` -That said, these APIs should *not* be considered stable, and are likely to -change: + - :ref:`django-admin utility `. + + - :ref:`Built-in middleware ` + + - :ref:`Request/response objects `. + + - :ref:`Settings `. Note, though that while the :ref:`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.'" + + - :ref:`Built-in signals `. Like settings, we'll probably add + new signals in the future, but the existing ones won't break. + + - :ref:`Unicode handling `. + + - Everything covered by the :ref:`HOWTO guides `. + +``django.utils`` +---------------- - - :ref:`Serialization ` is under development; changes - are possible. +Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of ``django.utils`` can be considered stable: - - Generic relations will most likely be moved out of core and into the - content-types contrib package to avoid core dependencies on optional - components. - - **New in development version**: this has now been done. + - ``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.safestring`` + - ``django.utils.tzinfo`` + - ``django.utils.encoding`` + +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. - - The comments framework, which is yet undocumented, will get a complete - rewrite before Django 1.0. diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt index 58b3193335..1528f78910 100644 --- a/docs/releases/1.0.txt +++ b/docs/releases/1.0.txt @@ -6,8 +6,18 @@ Django 1.0 release notes Welcome to Django 1.0! +Stability and forwards-compatibility +==================================== + +:ref:`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. + +See the :ref:`API stability guide ` for full details. + Porting guide -------------- +============= You can find detailed instructions on porting apps from Django 0.96 to Django 1.0 in our porting guide: