[Zodb-checkins] SVN: ZODB/branches/3.3/ News about ZEO protocol changes.

[Tim Peters]

Log message for revision 29784:
  News about ZEO protocol changes.
  

Changed:
  U   ZODB/branches/3.3/NEWS.txt
  U   ZODB/branches/3.3/README.txt

-=-
Modified: ZODB/branches/3.3/NEWS.txt
===================================================================
--- ZODB/branches/3.3/NEWS.txt	2005-04-01 16:08:47 UTC (rev 29783)
+++ ZODB/branches/3.3/NEWS.txt	2005-04-01 16:20:43 UTC (rev 29784)
@@ -43,7 +43,18 @@
 depending on platform, and should suffer far fewer (if any) intermittent
 "timed out waiting for storage to connect" failures.
 
+ZEO protocol and compatibility
+------------------------------
 
+ZODB 3.3 introduced multiversion concurrency control (MVCC), which required
+changes to the ZEO protocol.  The first 3.3 release should have increased
+the internal ZEO protocol version number (used by ZEO protocol negotiation
+when a client connects), but neglected to.  This has been repaired.
+
+Compatibility between pre-3.3 and post-3.3 ZEO clients and servers remains
+very limited.  See the newly updated ``Compatibility`` section in
+``README.txt`` for details.
+
 FileStorage
 -----------
 

Modified: ZODB/branches/3.3/README.txt
===================================================================
--- ZODB/branches/3.3/README.txt	2005-04-01 16:08:47 UTC (rev 29783)
+++ ZODB/branches/3.3/README.txt	2005-04-01 16:20:43 UTC (rev 29784)
@@ -19,7 +19,7 @@
 - ZConfig -- a Zope configuration language
 - documentation
 
-Our primary development platforms are Linux and Windows 2000.  The
+Our primary development platforms are Linux and Windows XP.  The
 test suite should pass without error on all of these platforms,
 although it can take a long time on Windows -- longer if you use
 ZoneAlarm.  Many particularly slow tests are skipped unless you pass
@@ -30,15 +30,33 @@
 
 ZODB 3.3.1 requires Python 2.3.4 or later.
 
-The Zope 2.8 and X3 releases should be compatible with this version of ZODB.
-Note that Zope 2.7 and higher includes ZEO, so this package should only be
-needed to run a ZEO server.
+The Zope X3 release should be compatible with this version of ZODB.  Zope 3
+and Zope 2.8 have moved to ZODB 3.4.  Note that Zope 2.7 and higher includes
+ZEO, so this package should only be needed to run a ZEO server.
 
-The ZEO server in ZODB 3.3.1 is currently incompatible with earlier
-versions of ZODB.  If you want to test the software, you must be
-running this release for both client and server.  A backwards
-compatibility mechanism will be provided in a later release.
+The ZEO in ZODB 3.3 is only partly compatible with earlier versions of ZODB.
+ZODB 3.3 uses multiversion concurrency control (MVCC), which is new in 3.3,
+and earlier ZEO servers do not support MVCC:  a 3.3 ZEO client cannot talk
+with an older ZEO server.  In the other direction, a 3.3 ZEO server can talk
+with older ZEO clients, but because the names of some basic classes have
+changed, if any 3.3 clients commit modifications to the database it's likely
+that the database will contain instances of classes that don't exist in
+(can't be loaded by) older ZEO clients.  For example, the database root
+object was an instance of ``ZODB.PersistentMapping.PersistentMapping`` before
+ZODB 3.3, but is an instance of ``persistent.mapping.PersistentMapping`` in
+ZODB 3.3.  A 3.3.1 client can still load a
+``ZODB.PersistentMapping.PersistentMapping`` object, but is this just an alias
+for ``persistent.mapping.PersistentMapping``, and an object of the latter
+type will be stored if a 3.3 client commits a change to the root object.  An
+older ZEO client cannot load the root object so changed.
 
+This limits migration possibilities:  a 3.3 ZEO server can be used with
+older ZEO clients and serve an older database, so long as no 3.3 ZEO
+clients commit changes to the database.  The most practical upgrade path
+is to bring up both servers and clients using 3.3.1, not trying to mix
+pre-3.3 and post-3.3 ZEO clients and servers.
+
+
 Prerequisites
 -------------