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

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/