Page History

...

Based on above options, we are looking at 3 things to identify a broker version, i.e., versionInt, versionId and versionString. Whether we use versionInt or versionId, client needs to keep track of what each versionInt/versionId supports. The major difference between versionInt and versionId is that versionInt do not care about internal versions, while versionId does. Since internal version is maintained as of now, going with Option 2 or 3 makes sense. Among option 2 and 3, option 2 has the minimal information required, the KIP suggests to go with option 2. 

Summary of the changes proposed as part of this KIP

...

1. Every time a protocol version changes, for any request/response, ApiVersion will be bumped up.
2. Protocol documentation will be versioned with ApiVersion. Every time there is a ApiVersion change, protocol documentation version needs to be updated and linked to main documentation page.
3. Deprecation of protocol version will be done via marking the version as deprecated on the protocol documentation.
4. On getting unknown protocol version, broker will send an empty response, instead of simply closing client connection.
5. Metadata response will be enhanced to also contain broker version, i.e., (versionId, versionString), of the responding broker.
6. Metadata request with single null topic and size of -1 can be used to fetch metadata response with only broker version information and no topic/broker info.
7. On receiving a metadata request with single null topic with size of -1, broker will respond without topics metadata, as this can lead to unnecessary penalty on large clusters.

...