Skip to content

Add design process #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robobario wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add design process #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ You can contribute by:

All bugs, tasks or enhancements are tracked as GitHub issues.
Issues which might be a good start for new contributors are marked with the “good-start” label.
Public API changes are required to follow the [Design Process](#design-process)

## DCO Signoff

Expand All @@ -35,6 +36,24 @@ The GitHub teams `@kroxylicious/code-reviewers` and `@kroxylicious/doc-reviewers

If you're willing to provide code and/or reviews to others then let one of the [project managers](PMs.md) know and we can add you to the relevant GitHub team.

## Design Process

All Public API changes must begin with a design proposal. This includes:

* New APIs or API endpoints
* Changes to existing API signatures or behavior
* Removal or deprecation of APIs

Public APIs include (but are not limited to):
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need to define public API for the Kroxylicious 1.0 proposal, and it's also helpful to refer to it from a CLAUDE.md, so I think we should actually have a single source of truth as an .md in the kroxylicious/kroxylicious repo.

We should also make it an exhaustive list "Public APIs are:" not "include (but not limited to)". Otherwise it's all a bit too vague.

* Proxy configuration YAML
* Filter configuration YAML
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can generalise this from Filter to Plugin configuration. But also we should be clear that this only applies to those Plugins provided by the project ("1st party plugins" is the phrase I would use, but maybe it's worth a sentence to define it in words).

* Kubernetes CRDs
* Operator manifested resources (like public bootstrap server addresses)
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't immediately understand what you meant here. But really I think this is mostly covered by the CRD part isn't it?

The semantics you want are a bit tricky, because it's not the kube resource themselves, so much as the visible parts of them. For example, so long as the hostname, port and expected protocol of a VC didn't change we are at liberty to change how those are provided in terms of the Kube resources.

* Filter API (and other plugins) interfaces
* Wire-protocol changes (e.g. format of encrypted data emitted by Proxy)
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: What about the test support maven modules? And the record tools module?

Aside: We should probably fix the split packages in those modules as part of Kroxylicious 1.0, so that we're moving towards having jars which are Java modules.


Design proposals should be submitted to the [design repository](https://github.com/kroxylicious/design).

Copy link
Copy Markdown
Member

@k-wall k-wall Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the cross posting of the design proposal kroxylicious-dev@googlegroups.com be part of the process?

Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, please! In fact I'd advocate:

  • When the PR is "Ready for Review" (i.e. it's fine to open it as a Draft a solicit feedback from individual etc, but then announce to the whole community when you're ready for feedback from the whole community)
  • If we end up doing formal voting on PRs: when asking to start the vote.
  • When and if the PR is accepted (i.e. merged).

## I just have a question

If you encounter any issues while using Kroxylicious, you can get help using:
Expand Down