Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
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
Showing
1 changed file
with
117 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Original file line | Diff line number | Diff line change |
---|---|---|---|
@@ -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/ |