Page History

...

With the newly proposed feature versioning system in this KIP, it becomes quite important to understand when to use it, and when not to.

When to use versioned feature versionsflags?

• A "breaking change" typically happens whenever the underlying Broker logic has introduced a different concept (such as a message type, or a new field in a protocol) which only certain newer versions of the Broker code can understand/process. The older Broker versions could consider the such a change to be alien i.e. the older Broker versions would could exhibit undefined or terminal behavior if they notice effects of the breaking change. Similarly, Kafka clients could exhibit undefined undesirable behavior if they start commence usage of a feature version on the cluster, assuming all Brokers support it, while in reality some Brokers don't.
  As part of Kafka operations, there are occasions when it becomes paramount necessary to safely activate certain breaking changes introduced by a newer Broker version. Such changes become good candidates to be released behind a feature flag . The cluster-wide max feature version level can be safely increased/finalized (using the provided mechanism in this KIP), after the cluster-wide deployment of the required Broker version is over. With this procedurethe versioning system in place, whenever the effects of the underlying breaking change is activated by the cluster operator, the versioning system provides a guarantee that it will not bring ill effects to the Broker cluster or the Kafka clientssystem protects the cluster and Kafka clients from bad effects due to breaking changes.
• As a guideline, min/ max supported feature version values should be modified increased if and only if the change is a breaking change. Also, min feature version value should be increased if and only if a feature version needs to be deprecated. Non-breaking changes or non-deprecating changes could continue to be made to the Broker code without modifying the feature version values.

...

• Most common workflow for the feature versioning system would involve finalizing a cluster upgrade to max feature version levels for all features, after completing the release of a new Kafka Broker binary on a cluster. This is explained  under Regular CLI tool usage section.
• Emergency downgrades of max version levels of features are rare, is rare especially after they are finalized  (because these are breaking changes, and finalizing these changes can have consequences). For such rare situations, the user could still downgrade specific features using the CLI tool. Also, all features can be downgraded using the CLI tool belonging to a specific Broker release. For examples of these, please refer to the Tooling support section.

...