You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by "Parkerhiphop (via GitHub)" <gi...@apache.org> on 2026/09/19 07:22:51 UTC
[PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Parkerhiphop opened a new pull request, #23522:
URL: https://github.com/apache/kafka/pull/23522
Follow-ups to #23125 and #23235 raised similar discussions about how unstable metadata versions should be maintained when bumping `LATEST_PRODUCTION`.
The existing comments mainly describe how unstable metadata versions affect users,
but do not explain why an unstable version needs to remain available for development
and testing. This makes it easy to miss the relationship between
`LATEST_PRODUCTION`, `latestTesting()`, and the default version used by `@ClusterTest`.
The comments now explain that:
- At least one unstable `MetadataVersion` should remain after `LATEST_PRODUCTION`.
- The latest unstable version serves as the development and testing version.
- Tests require `latestTesting()` to be newer than `LATEST_PRODUCTION`.
- The default metadata version in `@ClusterTest` should stay aligned with `MetadataVersion.latestTesting()`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "chia7712 (via GitHub) via jira" <ji...@kafka.apache.org>.
chia7712 commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4482117333
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -26,23 +26,22 @@
import java.util.stream.Collectors;
/**
- * This class contains the different Kafka versions.
- * Right now, we use them for upgrades - users can configure the version of the API brokers will use to communicate between themselves.
- * This is only for inter-broker communications - when communicating with clients, the client decides on the API version.
+ * This enum contains the different Kafka metadata versions.
+ * These versions are used during upgrades - users can configure which API version brokers use when communicating with each other.
Review Comment:
This description is out of date as well. The MV also controls the RPC versions to clients.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "mingyen066 (via GitHub)" <gi...@apache.org>.
mingyen066 commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4053606734
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,10 +135,14 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
+ //
+ // Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
+ // The latest unstable version serves as the development and testing version,
+ // and tests require latestTesting() > LATEST_PRODUCTION.
Review Comment:
nit: "and tests require latestTesting() > LATEST_PRODUCTION." is a bit vague to me. How about saying the action directly?
```suggestion
// Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
// The latest unstable version serves as the development and testing version.
// If LATEST_PRODUCTION becomes the last version, add a new unstable
// MetadataVersion for the next release.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub) via jira" <ji...@kafka.apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4512851467
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,16 +134,22 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
- // If users attempt to use an unstable MetadataVersion, they will get an error unless
- // they have set the configuration unstable.feature.versions.enable=true.
- // Please move this comment when updating the LATEST_PRODUCTION constant.
+ // The latest unstable version serves as the development and testing version.
+ // Attempts to use an unstable MetadataVersion will fail unless
+ // unstable.feature.versions.enable=true.
+ //
+ // NOTES when updating MetadataVersion:
+ // 1. Keep the default MetadataVersion in @ClusterTest aligned with
+ // MetadataVersion.latestTesting().
+ // 2. Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
+ // 3. When updating LATEST_PRODUCTION, keep LATEST_STABLE_METADATA_VERSION in
+ // tests/kafkatest/version.py aligned with it and move this entire comment
+ // block below the new LATEST_PRODUCTION constant.
Review Comment:
Adopted!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub)" <gi...@apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4092370092
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,10 +135,15 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
+ //
+ // Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
Review Comment:
@chia7712 Yes. I have consolidated them into one comment block.
I also rephrased the enum description for cleaner explanation.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "chia7712 (via GitHub)" <gi...@apache.org>.
chia7712 commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4058599328
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,10 +135,15 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
+ //
+ // Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
Review Comment:
There are too many "you should xxx" notes scattered across this file now. Could we consolidate them?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub)" <gi...@apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4343902491
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -26,23 +26,23 @@
import java.util.stream.Collectors;
/**
- * This class contains the different Kafka versions.
- * Right now, we use them for upgrades - users can configure the version of the API brokers will use to communicate between themselves.
- * This is only for inter-broker communications - when communicating with clients, the client decides on the API version.
+ * This enum contains the different Kafka metadata versions.
+ * These versions are used during upgrades - users can configure which API version brokers use when communicating with each other.
+ * This setting only affects inter-broker communication.
+ * For client-broker communication, the client determines the API version to use.
* <br>
- * Note that the ID we initialize for each version is important.
- * We consider a version newer than another if it is lower in the enum list (to avoid depending on lexicographic order)
+ * Note that the order of the versions in this enum is important.
+ * Versions are compared by their position in the enum rather than lexicographically.
* <br>
- * Since the api protocol may change more than once within the same release and to facilitate people deploying code from
- * trunk, we have the concept of internal versions (first introduced during the 1.0 development cycle). For example,
- * the first time we introduce a version change in a release, say 1.0, we will add a config value "1.0-IV0" and a
- * corresponding enum constant IBP_1_0-IV0. We will also add a config value "1.0" that will be mapped to the
- * latest internal version object, which is IBP_1_0-IV0. When we change the protocol a second time while developing
- * 1.0, we will add a new config value "1.0-IV1" and a corresponding enum constant IBP_1_0-IV1. We will change
- * the config value "1.0" to map to the latest internal version IBP_1_0-IV1. The config value of
- * "1.0-IV0" is still mapped to IBP_1_0-IV0. This way, if people are deploying from trunk, they can use
- * "1.0-IV0" and "1.0-IV1" to upgrade one internal version at a time. For most people who just want to use
- * released version, they can use "1.0" when upgrading to the 1.0 release.
+ * Since the API protocol may change multiple times during the development of a single release, we use internal versions to
+ * represent each protocol change.
+ * For example, when the first protocol change is introduced during the development of 1.0, we add the config value `1.0-IV0`
+ * and the corresponding enum constant `IBP_1_0_IV0`.
Review Comment:
@chia7712 Yes. It's better to use existed MV.
I updated the description with `IBP_3_5_IV0`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub)" <gi...@apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4092370092
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,10 +135,15 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
+ //
+ // Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
Review Comment:
@chia7712 Yes. I have consolidated them into one comment block.
I also rephrased the enum description for cleaner explanation.
cc @m1a2st
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub)" <gi...@apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4056538526
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,10 +135,14 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
+ //
+ // Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
+ // The latest unstable version serves as the development and testing version,
+ // and tests require latestTesting() > LATEST_PRODUCTION.
Review Comment:
@mingyen066 Thanks for the suggestion!
It turns the explanation into practical action.
Adopted it!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "chia7712 (via GitHub)" <gi...@apache.org>.
chia7712 commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4289270102
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -26,23 +26,23 @@
import java.util.stream.Collectors;
/**
- * This class contains the different Kafka versions.
- * Right now, we use them for upgrades - users can configure the version of the API brokers will use to communicate between themselves.
- * This is only for inter-broker communications - when communicating with clients, the client decides on the API version.
+ * This enum contains the different Kafka metadata versions.
+ * These versions are used during upgrades - users can configure which API version brokers use when communicating with each other.
+ * This setting only affects inter-broker communication.
+ * For client-broker communication, the client determines the API version to use.
* <br>
- * Note that the ID we initialize for each version is important.
- * We consider a version newer than another if it is lower in the enum list (to avoid depending on lexicographic order)
+ * Note that the order of the versions in this enum is important.
+ * Versions are compared by their position in the enum rather than lexicographically.
* <br>
- * Since the api protocol may change more than once within the same release and to facilitate people deploying code from
- * trunk, we have the concept of internal versions (first introduced during the 1.0 development cycle). For example,
- * the first time we introduce a version change in a release, say 1.0, we will add a config value "1.0-IV0" and a
- * corresponding enum constant IBP_1_0-IV0. We will also add a config value "1.0" that will be mapped to the
- * latest internal version object, which is IBP_1_0-IV0. When we change the protocol a second time while developing
- * 1.0, we will add a new config value "1.0-IV1" and a corresponding enum constant IBP_1_0-IV1. We will change
- * the config value "1.0" to map to the latest internal version IBP_1_0-IV1. The config value of
- * "1.0-IV0" is still mapped to IBP_1_0-IV0. This way, if people are deploying from trunk, they can use
- * "1.0-IV0" and "1.0-IV1" to upgrade one internal version at a time. For most people who just want to use
- * released version, they can use "1.0" when upgrading to the 1.0 release.
+ * Since the API protocol may change multiple times during the development of a single release, we use internal versions to
+ * represent each protocol change.
+ * For example, when the first protocol change is introduced during the development of 1.0, we add the config value `1.0-IV0`
+ * and the corresponding enum constant `IBP_1_0_IV0`.
Review Comment:
`IBP_1_0_IV0` was already removed. Could you refine the whole description based on current MVs?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "chia7712 (via GitHub) via jira" <ji...@kafka.apache.org>.
chia7712 commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4482150675
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -135,16 +134,22 @@ public enum MetadataVersion {
//
// NOTE: MetadataVersions after this point are unstable and may be changed.
- // If users attempt to use an unstable MetadataVersion, they will get an error unless
- // they have set the configuration unstable.feature.versions.enable=true.
- // Please move this comment when updating the LATEST_PRODUCTION constant.
+ // The latest unstable version serves as the development and testing version.
+ // Attempts to use an unstable MetadataVersion will fail unless
+ // unstable.feature.versions.enable=true.
+ //
+ // NOTES when updating MetadataVersion:
+ // 1. Keep the default MetadataVersion in @ClusterTest aligned with
+ // MetadataVersion.latestTesting().
+ // 2. Keep at least one unstable MetadataVersion after LATEST_PRODUCTION.
+ // 3. When updating LATEST_PRODUCTION, keep LATEST_STABLE_METADATA_VERSION in
+ // tests/kafkatest/version.py aligned with it and move this entire comment
+ // block below the new LATEST_PRODUCTION constant.
Review Comment:
```
move this entire comment block below the MetadataVersion that LATEST_PRODUCTION points to.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: Document unstable MetadataVersion requirements [kafka]
Posted by "Parkerhiphop (via GitHub) via jira" <ji...@kafka.apache.org>.
Parkerhiphop commented on code in PR #23522:
URL: https://github.com/apache/kafka/pull/23522#discussion_r4512866796
##########
server-common/src/main/java/org/apache/kafka/server/common/MetadataVersion.java:
##########
@@ -26,23 +26,22 @@
import java.util.stream.Collectors;
/**
- * This class contains the different Kafka versions.
- * Right now, we use them for upgrades - users can configure the version of the API brokers will use to communicate between themselves.
- * This is only for inter-broker communications - when communicating with clients, the client decides on the API version.
+ * This enum contains the different Kafka metadata versions.
+ * These versions are used during upgrades - users can configure which API version brokers use when communicating with each other.
Review Comment:
I updated the description to keep it up to date.
However, I'm not sure it's too general. Please have a look!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org