Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added notes on API stability in preparation for the 0.95 release.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3463 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 6537401ca45dcaeb8eb285bcf451e403f538eb93 1 parent 2a0af00
@jacobian jacobian authored
Showing with 117 additions and 0 deletions.
  1. +117 −0 docs/api_stability.txt
View
117 docs/api_stability.txt
@@ -0,0 +1,117 @@
+=============
+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.
+
+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
+ 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.
+
+ - We'll only break backwards compatibility of these APIs if a bug or
+ security hole makes it completely unavoidable.
+
+These APIs are stable:
+
+ - `Caching`_.
+
+ - `Custom template tags and libraries`_ (with the possible exception for a
+ small change in the way templates are registered and loaded).
+
+ - `Database lookup`_ (with the exception of validation; see below).
+
+ - `django-admin utility`_.
+
+ - `FastCGI integration`_.
+
+ - `Flatpages`_.
+
+ - `Generic views`_.
+
+ - `Internationalization`_.
+
+ - `Legacy database integration`_.
+
+ - `Model definition`_ (with the exception of generic relations; see below).
+
+ - `mod_python integration`_.
+
+ - `Redirects`_.
+
+ - `Request/response objects`_.
+
+ - `Sending email`_.
+
+ - `Sessions`_.
+
+ - `Settings`_.
+
+ - `Syndication`_.
+
+ - `Template language`_ (with the exception of some possible disambiguation
+ of how tag arguments are passed to tags and filters).
+
+ - `Transactions`_.
+
+ - `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.
+
+That said, these APIs should *not* be considered stable, and are likely to
+change:
+
+ - `Forms and validation`_ will most likely be compeltely rewritten to
+ deemphasize Manipulators in favor of validation-aware models.
+
+ - `Serialization`_ is under heavy development; changes are likely.
+
+ - The `authentication`_ framework is changing to be far more flexible, and
+ API changes may be necessary.
+
+ - Generic relations will most likely be moved out of core and into the
+ content-types contrib package to avoid core dependacies on optional
+ components.
+
+ - The comments framework, which is yet undocumented, will likely get a complete
+ rewrite before Django 1.0. Even if the change isn't quite that drastic,
+ there will at least be moderate changes.
+
+.. _caching: http://www.djangoproject.com/documentation/cache/
+.. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/
+.. _database lookup: http://www.djangoproject.com/documentation/db_api/
+.. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/
+.. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/
+.. _flatpages: http://www.djangoproject.com/documentation/flatpages/
+.. _generic views: http://www.djangoproject.com/documentation/generic_views/
+.. _internationalization: http://www.djangoproject.com/documentation/i18n/
+.. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/
+.. _model definition: http://www.djangoproject.com/documentation/model_api/
+.. _mod_python integration: http://www.djangoproject.com/documentation/modpython/
+.. _redirects: http://www.djangoproject.com/documentation/redirects/
+.. _request/response objects: http://www.djangoproject.com/documentation/request_response/
+.. _sending email: http://www.djangoproject.com/documentation/email/
+.. _sessions: http://www.djangoproject.com/documentation/sessions/
+.. _settings: http://www.djangoproject.com/documentation/settings/
+.. _syndication: http://www.djangoproject.com/documentation/syndication/
+.. _template language: http://www.djangoproject.com/documentation/templates/
+.. _transactions: http://www.djangoproject.com/documentation/transactions/
+.. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/
+.. _forms and validation: http://www.djangoproject.com/documentation/forms/
+.. _serialization: http://www.djangoproject.com/documentation/serialization/
+.. _authentication: http://www.djangoproject.com/documentation/authentication/
Please sign in to comment.
Something went wrong with that request. Please try again.