Changes between Version 31 and Version 32 of SessionMessages

Timestamp:

Oct 16, 2009, 12:38:31 PM (15 years ago)

Author:

Tobias McNulty

Comment:

update transition plan

SessionMessages

@@ -22 +22 @@
  * Reusable apps don't know what 3rd party system to use and hence cannot rely on providing session feedback 
 
-== Integrating with the Existing API ==
+== The Existing API ==
 
-It is not possible nor desirable to integrate with the existing API because it is tied directly to a related manager on the user model and cannot be extended to support the additional functionality in this proposal (without some ugly hacks).  There are several possible solutions to this conflict (we don't really need or want two messaging APIs in the core); feel free to add more:
+It seems to be the consensus on the mailing list that we have no desire to maintain two messaging APIs in the core and the proposed app will adequately replace all current uses of the [http://docs.djangoproject.com/en/dev/topics/auth/#messages existing message API].  It has been noted by several people, therefore, that we need a deprecation plan for removing the old API that makes the transition easy for any apps currently using it.
 
- * In the documentation, cast the user messaging API in a vary narrow use; e.g., for administrator messages to specific users
- * Phase out user messages entirely
+There are several parts to the user message API, each with different options for transition:
 
-=== Deprecation Plan ===
+ * '''models.User.message_set.create(message)''': because this is a just a related manager on a model, and we don't have access to the request (or much else) inside the create() method, it's not possible to override this method with one that stores messages in the new session or cookie backend.  It is, however, completely feasible to retrieve and display any messages set in the user Message model from the new app (see below).
 
-The thread on the mailing list seems to be leaning towards deprecating the old API rather than keeping it around in parallel with the new one.  If deprecating is the right answer, what follows is a rough plan of how that might play out.  Many details are still missing and the plan needs to be fleshed out further in the coming days/weeks.
+ * '''{{ messages }}''': Since this is set in a context processor, we can replace this variable in the template context with one that will lazily wrap messages stored in the user Message model and messages stored in the newer session and cookie backends.
+
+ * '''models.User.get_and_delete_messages()''': As with message_set.create, it is not possible to override this method with one that can retrieve messages from the proposed session and cookie backends.  In the transition API, however, it will continue to retrieve (and delete) messages stored in the user Message model via message_set.create (as it has in the past).
+
+=== Transition Plan ===
+
+What follows is a rough plan of how to introduce the new API and deprecate the existing one.  Some details are still missing and the plan needs to be fleshed out further in the coming days/weeks.
 
  * '''Django 1.2'''
     * Introduce the proposed messaging app
-    * Deprecate the existing API and mark it as such in the documentation.  Retain the same functionality.
-    * contrib apps in Django still use the old API
+    * Replace {{ messages }} with lazily loaded messages from both the old (user message) and new (session/cookie) storages
+    * Deprecate the existing API and mark it as such in the documentation.  Retain the same functionality.  Raise a PendingDeprecationWarning when used.
+    * Update contrib apps (auth and admin) and generic views (create_object, update_object, and delete_object) in Django to use the new API
  * '''Django 1.3'''
-    * Update all contrib apps in Django to use the new API
-    * Retain the same functionality in the old API, but raise a deprecation warning when it is used
+    * Retain the same functionality in the old API, but raise a DeprecationWarning when it is used
  * '''Django 1.4'''
     * Remove the old API.  This includes the Message model and any methods in contrib.auth that use it (such as get_and_delete_messages).