This is an automated email from the ASF dual-hosted git repository.
mimaison pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/kafka-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 90621af2 MINOR: Update coding guide to mention need to maintain public
client API compatibility (#379)
90621af2 is described below
commit 90621af2c09eb2c4775e033defafef9f1723dcd6
Author: Stanislav Kozlovski <[email protected]>
AuthorDate: Tue May 3 15:02:00 2022 +0300
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 <[email protected]>, Justine Olshan
<[email protected]>, Luke Chen <[email protected]>
---
coding-guide.html | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/coding-guide.html b/coding-guide.html
index 624ddcb1..22ade9fa 100644
--- a/coding-guide.html
+++ b/coding-guide.html
@@ -13,7 +13,7 @@
<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,7 +92,7 @@
<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" p [...]
+ <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 wou [...]
<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 r [...]
</ul>
@@ -100,7 +100,7 @@
<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>
