svn commit: r1158352 - /incubator/kafka/site/coding-guide.html

[jk...@apache.org]

Author: jkreps
Date: Tue Aug 16 16:22:35 2011
New Revision: 1158352

URL: http://svn.apache.org/viewvc?rev=1158352&view=rev
Log:
Clarify backwards compatability statement (not necessarily mandatory, give example of versions).


Modified:
    incubator/kafka/site/coding-guide.html

Modified: incubator/kafka/site/coding-guide.html
URL: http://svn.apache.org/viewvc/incubator/kafka/site/coding-guide.html?rev=1158352&r1=1158351&r2=1158352&view=diff
==============================================================================
--- incubator/kafka/site/coding-guide.html (original)
+++ incubator/kafka/site/coding-guide.html Tue Aug 16 16:22:35 2011
@@ -88,7 +88,7 @@ We are following the style guide given <
 
 <h2>Backwards Compatibility</h2>
 <ul>
-<li>Our policy is that we should always support backwards compatibility for one release to enable no-downtime upgrades. This means the server MUST be able to support requests from both old and new clients simultaneously. The code handling the "old" path can be removed in the next release. A typical upgrade sequence would be server, consumers, clients.</li>
+<li>Our policy is that the Kafka protocols and data formats should support backwards compatibility for one release to enable no-downtime upgrades (unless there is a <i>very</i> compelling counter-argument). This means the server MUST be able to support requests from both old and new clients simultaneously. This compatability need only be retained for one release (e.g. 0.7 must accept requests from 0.6 clients, but this need not be maintained indefinitely). The code handling the "old" path can be removed in the next release or whenever we can get all the clients up-to-date. A typical upgrade sequence for binary format changes would be (1) upgrade consumers to handle new message format, (2) upgrade server, (3) clients.</li>
 <li>There are three things which require this binary compatibility: request objects, persistent data structure (messages and message sets), and zookeeper structures and protocols. The message binary structure has a "magic" byte to allow it to be evolved, this number should be incremented when the format is changed and the number can be checked to apply the right logic and fill in defaults appropriately. Network requests have a request id which serve a similar purpose, any change to a request object must be accompanied by a change in the request id. Any change here should be accompanied by compatibility tests that save requests or messages in the old format as a binary file which is tested for compatibility with the new code.</li>
 </ul>