diff options
Diffstat (limited to 'google_appengine/lib/django/docs/api_stability.txt')
| -rw-r--r-- | google_appengine/lib/django/docs/api_stability.txt | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/google_appengine/lib/django/docs/api_stability.txt b/google_appengine/lib/django/docs/api_stability.txt new file mode 100644 index 0000000..508336e --- /dev/null +++ b/google_appengine/lib/django/docs/api_stability.txt @@ -0,0 +1,123 @@ +============= +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. + +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 + 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. + +Stable APIs +=========== + +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 completely 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 dependancies 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: ../cache/ +.. _custom template tags and libraries: ../templates_python/ +.. _database lookup: ../db_api/ +.. _django-admin utility: ../django_admin/ +.. _fastcgi integration: ../fastcgi/ +.. _flatpages: ../flatpages/ +.. _generic views: ../generic_views/ +.. _internationalization: ../i18n/ +.. _legacy database integration: ../legacy_databases/ +.. _model definition: ../model_api/ +.. _mod_python integration: ../modpython/ +.. _redirects: ../redirects/ +.. _request/response objects: ../request_response/ +.. _sending email: ../email/ +.. _sessions: ../sessions/ +.. _settings: ../settings/ +.. _syndication: ../syndication/ +.. _template language: ../templates/ +.. _transactions: ../transactions/ +.. _url dispatch: ../url_dispatch/ +.. _forms and validation: ../forms/ +.. _serialization: ../serialization/ +.. _authentication: ../authentication/ |