From 75908721389df0376d2d6170e9601590add226d7 Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Mon, 20 Oct 2025 18:25:59 +1300 Subject: [PATCH 1/6] Propose a v1.0 and use of patch versions Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 91 +++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 proposals/007-kroxylicious-1.0.md diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md new file mode 100644 index 0000000..3bb6c71 --- /dev/null +++ b/proposals/007-kroxylicious-1.0.md @@ -0,0 +1,91 @@ + + +# Kroxylicious 1.0 and patch releases + +This proposal is for a Kroxylicious 1.0 release, and an improved commitment to making patch releases. + +## Current situation + +Kroxylicious already uses [Semantic Versioning][semver], but so far all releases have been `0.x.y` versions. + +The project currently promises API compatibilty covering at "least 3 releases, and at least 3 months". + +So far, we have done patch releases (i.e. releases like `0.x.1`) only when a new minor release with a fix is not already released, and not imminent. + +## Motivation + +Under semantic versioning, releases with a major number of 0 are allowed to break compatibility with previous releases. +The software released by project is maturing, and existing users would benefit from having a stronger guarantee about when compatibility between releases might be broken. + +At this time there are already a number of users using Kroxylicious in production, however, some potential users might be put off from adopting Kroxylicious by the `0.` version number. +A 1.0 release would be a signal that we believe Kroxylicious is production-ready. + +## Proposal + +# What will have a compatibility guarantee? + +We propose that the release that was going to be called `0.18.0` instead be called `1.0`. +By implication of Semantic Versioning, that means we would be committing to not breaking compatibilty until some future `2.0` release. +The time of such a `2.0` release is currently neither known nor planned. + +For the avoidance of doubt, this compatibilty guarantee would cover: + +1. Binary compatibility of the Java APIs of the following modules: + * `kroxylicious-api` + * `kroxylicious-kms` +2. The format of the proxy configuration file, including the configuration of certain plugins provided by the project. Compatibility here means that a released version `1.y` would accept any configuration file that was accepted as valid in any released `1.x` version, where `y > x`. "Valid" means the proxy starts up cleanly. +3. The plugins covered under item 2. are: + * `kroxylicious-record-encryption` +4. The Kubernetes custom resource APIs defined by the kroxylicious-operator. + +If the compatibility guarantee is broken we will treat that as a bug. + +# What is the commitment for patch releases? + +In terms of patch releases, the project needs to strike a balance between: + +* what the community can sustainably deliver to end users, +* what users would like. + +The use of the term "the community" in the above is important. +The promises being made here are somewhat contingent on support from the community: +If you want a bug fixed but the maintainers do not think it's a priority, you will need to fix it and backport it yourself if you want to see a fix in an official release. + +Under semver, patch releases only contain bug fixes. They do not contain new features. +We interpret "bug fixes" to include: + +* Bug fixes in Kroxylicious itself, where the bug has been fixed, and back ported to the relevant patch branch. +* exploitable CVEs in dependencies and transitive dependencies, where a fixed version of the dependency has been released. +* exploitable CVEs in Docker images, including in a base image, where a fixed version of the base image has been released. + +Note that if a bug is fixed by a new feature merged to `main` then it won't be eligable to be merged to a patch release branch. + +We propose to provide patch releases for current `1.x`, plus up to the previous two minor releases. I.e. If the current release is `1.x.y` then we are prepared to release a `1.x.(y+1)`, `1.(x-1).z` and `1.(x-2).z`. +However, the "up to" is limited to 6 months after the initial minor release. +So if `1.(x-2).0` was released more than 6 months ago, there is no promise to release a `1.(x-2).z`; it will be at the maintainers' discretion. +This is not a commitment to either: +* fix any particular bug found in `1.x` +* nor to release back-ported fixes immediately, because releases have a cost. + +We expect the process to work similarly to the Kafka project itself: + +1. Fixes should always be made to the tip-most branch that is affected by the bug, and subsequently back ported to the branches for other affected releases. Often, this will mean PRs should be opened against `main`, and back ported to the `1.x` minor branch. +2. When enough bugs have been fixed to justify the effort of doing a release, we will start a release process, creating a patch branch from the minor branch. +3. Just because some fixes have been merged to a given patch branch does not imply a patch release needs to be made (for example if it's been more than 6 months since the initial release from that minor branch. + +Users, or potential users, for whom the above commitments are insufficient are advised to find a commercial software vendor who can provide the necessary level of support for Kroxylicious. + +## Affected/not affected projects + +This proposal concerns the kroxylicious/kroxylicious github projects, and the releases that originate from it. + +## Compatibility + +This the subject of this proposal and has already been described, above. + +## Rejected alternatives + +The only alternative is to stick with `0.x` numbering for some amount time. +At the end of the day, the move to 1.0 is more of a subject judgement call than something based on objective criteria. + +[semver]: https://semver.org/ From f5f28bb275a35f815cdbee97b03bcc1d5d448d2e Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Tue, 21 Oct 2025 09:41:32 +1300 Subject: [PATCH 2/6] Tweaks Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md index 3bb6c71..eca71ed 100644 --- a/proposals/007-kroxylicious-1.0.md +++ b/proposals/007-kroxylicious-1.0.md @@ -1,5 +1,3 @@ - - # Kroxylicious 1.0 and patch releases This proposal is for a Kroxylicious 1.0 release, and an improved commitment to making patch releases. @@ -22,7 +20,7 @@ A 1.0 release would be a signal that we believe Kroxylicious is production-ready ## Proposal -# What will have a compatibility guarantee? +### What will have a compatibility guarantee? We propose that the release that was going to be called `0.18.0` instead be called `1.0`. By implication of Semantic Versioning, that means we would be committing to not breaking compatibilty until some future `2.0` release. @@ -36,20 +34,27 @@ For the avoidance of doubt, this compatibilty guarantee would cover: 2. The format of the proxy configuration file, including the configuration of certain plugins provided by the project. Compatibility here means that a released version `1.y` would accept any configuration file that was accepted as valid in any released `1.x` version, where `y > x`. "Valid" means the proxy starts up cleanly. 3. The plugins covered under item 2. are: * `kroxylicious-record-encryption` + * `kroxylicious-kms-provider-aws-kms` + * `kroxylicious-kms-provider-fortanix-dsm` + * `kroxylicious-kms-provider-hashicorp-vault` 4. The Kubernetes custom resource APIs defined by the kroxylicious-operator. If the compatibility guarantee is broken we will treat that as a bug. -# What is the commitment for patch releases? +### Minor and patch branches -In terms of patch releases, the project needs to strike a balance between: +The project needs to strike a balance between: * what the community can sustainably deliver to end users, * what users would like. The use of the term "the community" in the above is important. The promises being made here are somewhat contingent on support from the community: -If you want a bug fixed but the maintainers do not think it's a priority, you will need to fix it and backport it yourself if you want to see a fix in an official release. +If you want a bug fixed, but the maintainers do not think it's a priority, you will need to fix it and backport it yourself if you want to see a fix in an official release. + +We expect the process to work similarly to the Kafka project itself: + +Fixes should always be made to the tip-most branch that is affected by the bug, and subsequently back-ported to the branches for other affected versions. Often, this will mean PRs should be opened against `main`, and back ported to the `1.x` minor branch. Under semver, patch releases only contain bug fixes. They do not contain new features. We interpret "bug fixes" to include: @@ -60,6 +65,8 @@ We interpret "bug fixes" to include: Note that if a bug is fixed by a new feature merged to `main` then it won't be eligable to be merged to a patch release branch. +# Patch releases + We propose to provide patch releases for current `1.x`, plus up to the previous two minor releases. I.e. If the current release is `1.x.y` then we are prepared to release a `1.x.(y+1)`, `1.(x-1).z` and `1.(x-2).z`. However, the "up to" is limited to 6 months after the initial minor release. So if `1.(x-2).0` was released more than 6 months ago, there is no promise to release a `1.(x-2).z`; it will be at the maintainers' discretion. @@ -67,11 +74,9 @@ This is not a commitment to either: * fix any particular bug found in `1.x` * nor to release back-ported fixes immediately, because releases have a cost. -We expect the process to work similarly to the Kafka project itself: +When enough bugs have been fixed to justify the effort of doing a release, we will start a release process, creating a patch branch from the tip of the minor branch. -1. Fixes should always be made to the tip-most branch that is affected by the bug, and subsequently back ported to the branches for other affected releases. Often, this will mean PRs should be opened against `main`, and back ported to the `1.x` minor branch. -2. When enough bugs have been fixed to justify the effort of doing a release, we will start a release process, creating a patch branch from the minor branch. -3. Just because some fixes have been merged to a given patch branch does not imply a patch release needs to be made (for example if it's been more than 6 months since the initial release from that minor branch. +Just because some fixes have been merged to a given patch branch does not imply a patch release needs to be made. For example, if it's been more than 6 months since the initial release from that minor branch. Users, or potential users, for whom the above commitments are insufficient are advised to find a commercial software vendor who can provide the necessary level of support for Kroxylicious. From 93410d2848d134d403e5862ff46e8d4ad4c20fa2 Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Tue, 28 Oct 2025 22:26:06 +0000 Subject: [PATCH 3/6] Apply suggestion from @hrishabhg Co-authored-by: Hrishabh Gupta Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md index eca71ed..61d1b83 100644 --- a/proposals/007-kroxylicious-1.0.md +++ b/proposals/007-kroxylicious-1.0.md @@ -22,7 +22,7 @@ A 1.0 release would be a signal that we believe Kroxylicious is production-ready ### What will have a compatibility guarantee? -We propose that the release that was going to be called `0.18.0` instead be called `1.0`. +We propose that the release that was going to be called `0.18.0` instead be called `1.0.0`. By implication of Semantic Versioning, that means we would be committing to not breaking compatibilty until some future `2.0` release. The time of such a `2.0` release is currently neither known nor planned. From 95b26c30333f9906c9bfa1615cfdb3c25b671d10 Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Tue, 28 Oct 2025 22:30:48 +0000 Subject: [PATCH 4/6] Apply suggestion from @tombentley Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md index 61d1b83..b4fcceb 100644 --- a/proposals/007-kroxylicious-1.0.md +++ b/proposals/007-kroxylicious-1.0.md @@ -24,7 +24,7 @@ A 1.0 release would be a signal that we believe Kroxylicious is production-ready We propose that the release that was going to be called `0.18.0` instead be called `1.0.0`. By implication of Semantic Versioning, that means we would be committing to not breaking compatibilty until some future `2.0` release. -The time of such a `2.0` release is currently neither known nor planned. +The time of such a `2.0` release is to be decided, but anticipated to be very approximately 12 months after a `1.0` release. For the avoidance of doubt, this compatibilty guarantee would cover: From 848d1ebbb9277b097e6e9d5fc48392e065f5710e Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Tue, 28 Oct 2025 22:31:53 +0000 Subject: [PATCH 5/6] Apply suggestion from @gracegrimwood Co-authored-by: Grace Grimwood <15976368+gracegrimwood@users.noreply.github.com> Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md index b4fcceb..ce22c2a 100644 --- a/proposals/007-kroxylicious-1.0.md +++ b/proposals/007-kroxylicious-1.0.md @@ -86,7 +86,7 @@ This proposal concerns the kroxylicious/kroxylicious github projects, and the re ## Compatibility -This the subject of this proposal and has already been described, above. +This is the subject of this proposal and has already been described, above. ## Rejected alternatives From e11a8b07c10aa0cd40ffe0a626a2ef19af910cf9 Mon Sep 17 00:00:00 2001 From: Tom Bentley Date: Wed, 29 Oct 2025 12:34:12 +1300 Subject: [PATCH 6/6] Changes for review comments Signed-off-by: Tom Bentley --- proposals/007-kroxylicious-1.0.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/proposals/007-kroxylicious-1.0.md b/proposals/007-kroxylicious-1.0.md index ce22c2a..c0d9f8a 100644 --- a/proposals/007-kroxylicious-1.0.md +++ b/proposals/007-kroxylicious-1.0.md @@ -32,11 +32,7 @@ For the avoidance of doubt, this compatibilty guarantee would cover: * `kroxylicious-api` * `kroxylicious-kms` 2. The format of the proxy configuration file, including the configuration of certain plugins provided by the project. Compatibility here means that a released version `1.y` would accept any configuration file that was accepted as valid in any released `1.x` version, where `y > x`. "Valid" means the proxy starts up cleanly. -3. The plugins covered under item 2. are: - * `kroxylicious-record-encryption` - * `kroxylicious-kms-provider-aws-kms` - * `kroxylicious-kms-provider-fortanix-dsm` - * `kroxylicious-kms-provider-hashicorp-vault` +3. The plugins covered under item 2. are all those implementations of the APIs listed in 1. provided by the project, excluding those implementations in test packages and modules. This implies the contined inclusion of these plugins in the `1.x` series of releases. However, the existing multi-tenancy plugin will be marked as deprecated. 4. The Kubernetes custom resource APIs defined by the kroxylicious-operator. If the compatibility guarantee is broken we will treat that as a bug. @@ -54,7 +50,7 @@ If you want a bug fixed, but the maintainers do not think it's a priority, you w We expect the process to work similarly to the Kafka project itself: -Fixes should always be made to the tip-most branch that is affected by the bug, and subsequently back-ported to the branches for other affected versions. Often, this will mean PRs should be opened against `main`, and back ported to the `1.x` minor branch. +Fixes should always be made to the tip-most branch that is affected by the bug, and subsequently back-ported to the branches for other affected versions. Often, this will mean PRs should be opened against `main`, and back ported to the `1.x` branch, and eventually released under a `1.x.y` tag. Under semver, patch releases only contain bug fixes. They do not contain new features. We interpret "bug fixes" to include: @@ -63,10 +59,12 @@ We interpret "bug fixes" to include: * exploitable CVEs in dependencies and transitive dependencies, where a fixed version of the dependency has been released. * exploitable CVEs in Docker images, including in a base image, where a fixed version of the base image has been released. -Note that if a bug is fixed by a new feature merged to `main` then it won't be eligable to be merged to a patch release branch. +Note that new features merged to `main` will not be eligible to be backported to a minor release branch. # Patch releases +Although described in terms of `1.x`, the following would apply `2.0` and future major versions. + We propose to provide patch releases for current `1.x`, plus up to the previous two minor releases. I.e. If the current release is `1.x.y` then we are prepared to release a `1.x.(y+1)`, `1.(x-1).z` and `1.(x-2).z`. However, the "up to" is limited to 6 months after the initial minor release. So if `1.(x-2).0` was released more than 6 months ago, there is no promise to release a `1.(x-2).z`; it will be at the maintainers' discretion.