Add DeprecationWarning: IStorage.tpc_finish will have to return the c…

…ommitted tid

src/ZODB/Connection.py

@@ -818,8 +818,23 @@ def callback(tid):
                     if obj is not None and obj._p_changed is not None:
                         obj._p_changed = 0
                         obj._p_serial = serial
+        else:
+            self._warn_about_returned_serial()
         self._tpc_cleanup()
 
+    def _warn_about_returned_serial(self):
+        # Do not warn about own implementations of ZODB.
+        # We're aware and the user can't do anything about it.
+        if self._normal_storage.__module__.startswith("_ZODB."):
+            self._warn_about_returned_serial = lambda: None
+        else:
+            warnings.warn(
+                "In ZODB 5+, it will be required for tpc_finish to return the"
+                " committed tid. store/tpc_vote will only have to notify about"
+                " resolved conflicts.",
+                DeprecationWarning, 2)
+            Connection._warn_about_returned_serial = lambda self: None
+
     def sortKey(self):
         """Return a consistent sort key for this connection."""
         return "%s:%s" % (self._storage.sortKey(), id(self))

src/ZODB/interfaces.py

@@ -776,10 +776,12 @@ def tpc_finish(transaction, func = lambda tid: None):
         called while the storage transaction lock is held.  It takes
         the new transaction id generated by the transaction.
 
-        The return value can be either None or a serial giving new
+        The return value must be the committed tid. It is used to set the
         serial for objects whose ids were passed to previous store calls
-        in the same transaction, and for which no serial was returned
-        from either store or tpc_vote for objects passed to store.
+        in the same transaction.
+
+        For compatibility, the return value can also be None, in which case
+        store/tpc_vote must return the serial of stored objects.
         """
 
     def tpc_vote(transaction):