docs/misc/api-stability.txt

   1 .. _misc-api-stability:
   2
   3 =============
   4 API stability
   5 =============
   6
   7 Although Django has not reached a 1.0 release, the bulk of Django's public APIs are
   8 stable as of the 0.95 release. This document explains which APIs will and will not
   9 change before the 1.0 release.
  10
  11 What "stable" means
  12 ===================
  13
  14 In this context, stable means:
  15
  16    - All the public APIs -- everything documented in the linked documents, and
  17      all methods that don't begin with an underscore -- will not be moved or
  18      renamed without providing backwards-compatible aliases.
  19
  20    - If new features are added to these APIs -- which is quite possible --
  21      they will not break or change the meaning of existing methods. In other
  22      words, "stable" does not (necessarily) mean "complete."
  23
  24    - If, for some reason, an API declared stable must be removed or replaced, it
  25      will be declared deprecated but will remain in the API until at least
  26      version 1.1. Warnings will be issued when the deprecated method is
  27      called.
  28
  29    - We'll only break backwards compatibility of these APIs if a bug or
  30      security hole makes it completely unavoidable.
  31
  32 Stable APIs
  33 ===========
  34
  35 These APIs are stable:
  36
  37    - :ref:`Caching <topics-cache>`.
  38
  39    - :ref:`Custom template tags and libraries <howto-custom-template-tags>`.
  40
  41    - :ref:`Database lookup <topics-db-queries>` (with the exception of validation; see below).
  42
  43    - :ref:`django-admin utility <ref-django-admin>`.
  44
  45    - :ref:`FastCGI and mod_python integration <howto-deployment-index>`.
  46
  47    - :ref:`Flatpages <ref-contrib-flatpages>`.
  48
  49    - :ref:`Generic views <topics-http-generic-views>`.
  50
  51    - :ref:`Internationalization <topics-i18n>`.
  52
  53    - :ref:`Legacy database integration <howto-legacy-databases>`.
  54
  55    - :ref:`Model definition <topics-db-models>` (with the exception of generic relations; see below).
  56
  57    - :ref:`Redirects <ref-contrib-redirects>`.
  58
  59    - :ref:`Request/response objects <ref-request-response>`.
  60
  61    - :ref:`Sending e-mail <topics-email>`.
  62
  63    - :ref:`Sessions <topics-http-sessions>`.
  64
  65    - :ref:`Settings <topics-settings>`.
  66
  67    - :ref:`Syndication <ref-contrib-syndication>`.
  68
  69    - :ref:`Template language <topics-templates>` (with the exception of some
  70      possible disambiguation of how tag arguments are passed to tags and
  71      filters).
  72
  73    - :ref:`Transactions <topics-db-transactions>`.
  74
  75    - :ref:`URL dispatch <topics-http-urls>`.
  76
  77 You'll notice that this list comprises the bulk of Django's APIs. That's right
  78 -- most of the changes planned between now and Django 1.0 are either under the
  79 hood, feature additions, or changes to a few select bits. A good estimate is
  80 that 90% of Django can be considered forwards-compatible at this point.
  81
  82 That said, these APIs should *not* be considered stable, and are likely to
  83 change:
  84
  85    - :ref:`Serialization <topics-serialization>` is under development; changes
  86      are possible.
  87
  88    - Generic relations will most likely be moved out of core and into the
  89      content-types contrib package to avoid core dependencies on optional
  90      components.
  91
  92      **New in development version**: this has now been done.
  93
  94    - The comments framework, which is yet undocumented, will get a complete
  95      rewrite before Django 1.0.