Skip to content
Permalink
Browse files
MINOR: Update coding guide to mention need to maintain public client …
…API compatibility (#379)

Previously, the coding guide would imply that it's acceptable to break API compatibility due to the project's early stage in maturity. For years now, the project has been mature and adopted enough to warrant not breaking API compatibility.

Reviewers: Mickael Maison <mickael.maison@gmail.com>, Justine Olshan <jolshan@confluent.io>, Luke Chen <showuon@gmail.com>
  • Loading branch information
stanislavkozlovski committed May 3, 2022
1 parent 8f6d53b commit 90621af2c09eb2c4775e033defafef9f1723dcd6
Showing 1 changed file with 3 additions and 3 deletions.
@@ -13,7 +13,7 @@ <h2>Basic Stuff</h2>
<ul>
<li>Avoid cryptic abbreviations. Single letter variable names are fine in very short methods with few variables, otherwise make them informative.</li>
<li>Clear code is preferable to comments. When possible make your naming so good you don't need comments. When that isn't possible comments should be thought of as mandatory, write them to be <i>read</i>.</li>
<li>Logging, configuration, and public APIs are our "UI". Make them pretty, consistent, and usable.</li>
<li>Logging, configuration, and public APIs are our "UI". Pay special attention to them and make them pretty, consistent, and usable.</li>
<li>There is not a maximum line length (certainly not 80 characters, we don't work on punch cards any more), but be reasonable.</li>
<li>Don't be sloppy. Don't check in commented out code: we use version control, it is still there in the history. Don't leave TODOs in the code or FIXMEs if you can help it. Don't leave println statements in the code. Hopefully this is all obvious.</li>
<li>We want people to use our stuff, which means we need clear, correct documentation. User documentation should be considered a part of any user-facing the feature, just like unit tests or performance results.</li>
@@ -92,15 +92,15 @@ <h2>Concurrency</h2>

<h2>Backwards Compatibility</h2>
<ul>
<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>Our policy is that the Kafka protocols and data formats should support backwards compatibility for as many releases 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 compatibility needs to be retained for at least one major release (e.g. 2.0 must accept requests from 1.0 clients). A typical upgrade sequence for binary format changes would be (1) upgrade server to handle the new message format, (2) upgrade clients to use the new message format.</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>

<h2>Client Code</h2>
<p>There are a few things that need to be considered in client code that are not a major concern on the server side.</p>
<ul>
<li>Libraries needed by the client should be avoided whenever possible. Clients are run in someone else's code and it is very possible that they may have the same library we have, but a different and incompatible version. This will mean they can't use our client. For this reason the client should not use any libraries that are not strictly necessary.</li>
<li>We should attempt to maintain API compatibility when possible, though at this point in the project's lifecycle it is more important to make things good rather than avoid breakage.</li>
<li>We should maintain API compatibility. Any incompatible changes should be ultimately settled in the KIP design process, where the usual strategy is to retain the old APIs, mark them as deprecated and potentially remove them in some next major release.</li>
</ul>

<h2>Streams API</h2>

0 comments on commit 90621af

Please sign in to comment.