Author: jacob Date: 2006-07-27 13:12:53 -0500 (Thu, 27 Jul 2006) New Revision: 3463
Added: django/trunk/docs/api_stability.txt Log: Added notes on API stability in preparation for the 0.95 release. Added: django/trunk/docs/api_stability.txt =================================================================== --- django/trunk/docs/api_stability.txt (rev 0) +++ django/trunk/docs/api_stability.txt 2006-07-27 18:12:53 UTC (rev 3463) @@ -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/ \ No newline at end of file --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/django-updates -~----------~----~----~----~------~----~------~--~---
