Add proposals index and resolve number collisions

[k-wall]

Summary

This PR introduces a proposal index (proposals/README.md) to solve the problem of colliding proposal numbers and establish a clear process for allocating proposal numbers.

Problem

Currently, multiple open proposal PRs have chosen numbers that conflict with already-merged proposals:

• PR Routing API #70 uses 004 (conflicts with "Terminology for Authentication")
• PR Kroxylicious 1.0 #82 uses 007 (conflicts with "Azure KMS Implementation")
• PR 012 - Hot reload feature proposal #83 uses 012 (no conflict currently)
• PR 014 - Proposal to refactor frontend handler and centralize session context #88 uses 014 (conflicts with "Operator namespace restriction")
• PR feat: Virtual cluster lifecycle state model #89 uses 016 (no conflict currently)
• Several others use placeholder names like nnn- or xxx-

This creates confusion and makes it difficult to maintain stable identifiers for proposals. When we discuss proposals on the mailing list, we need a consistent way to reference them throughout the discussion period, not just after they're merged.

Solution

This PR adds:

1. A proposal index (proposals/README.md) that lists:

   • All open proposals (with PR links)
   • All accepted proposals (with file links)
   • Clear identification of number collisions

2. A defined process for proposal authors:

   • Create proposal PR with temporary filename (nnn-my-proposal.md)
   • Raise separate PR to allocate next sequential number in the index
   • Rename proposal file once number is allocated
   • Update index when proposal is accepted/merged

3. Chronological numbering of open proposals to resolve collisions:

   • PR Routing API #70 → Proposal 016 (Routing API)
   • PR Kroxylicious 1.0 #82 → Proposal 017 (Kroxylicious 1.0)
   • PR 012 - Hot reload feature proposal #83 → Proposal 018 (Hot Reload)
   • PR Security audit logging #85 → Proposal 019 (Audit logging)
   • PR 014 - Proposal to refactor frontend handler and centralize session context #88 → Proposal 020 (Frontend Handler Refactoring)
   • PR feat: Virtual cluster lifecycle state model #89 → Proposal 021 (Virtual Cluster Lifecycle)
   • PR Strimzi v1 migration proposal #92 → Proposal 022 (Strimzi v1 migration)
   • PR 93 - Correlated request/response data API #93 → Proposal 023 (Request/Response Contextual Data API)
   • PR Add a proposal to deprecate io.kroxylicious.proxy.config.tls #94 → Proposal 024 (Cleaning up TLS configurations)

Benefits

• Stable identifiers: Each proposal gets a number before mailing list discussion
• No collisions: Sequential allocation prevents conflicts
• Clear visibility: Easy to see which proposals are open vs. accepted
• Chronological ordering: Numbers reflect the order proposals were created

🤖 Assisted-By: Claude Sonnet 4.5

[k-wall]

If this PR is accepted, I'll update the PR titles of the existing proposals to carry their assigned numbers.

[k-wall]

Fork this repo and...

[k-wall]

add "you may make this change in the PR of your proposal itself, as a separate commit. A separate PR is also fine".

[k-wall]

fix the URL syntax

[k-wall]

If this PR is accepted, I'll update the PR titles to carry the new numbers.

[robobario]

was wondering whether using PR number might be nicer. They'll still be chronological but then reffing #92 would also refer to proposal number 92.

[tombentley]

was wondering whether using PR number might be nicer. They'll still be chronological but then reffing #92 would also refer to proposal number 92.

I think that's quite appealing, actually.

• Reffing like Add proposals index and resolve number collisions #95 would be really nice.
• Personally I don't mind if proposals have non-contiguous numbers; uniqueness of identification and monotonicity are enough for me.
• I don't think there's really any value in maintaining a separate index -- the directory listing is good enough for me. If we want to be fancy about it we could wire up an LLM to check that the file name is a good summary of the content.

A couple of other things give me pause with our current model (which are not addressed by this proposal, I just wanted to get them out there, and this feels like an opportunity to do so):

• Personally I would value a way to keep the history of propsals that don't get accepted. The problem here is my experience with Kafka is that proposals sometimes spend a long time in discussion, and might eventually be accepted, but often not. There's no obvious point at which to merge the PR. I think this is a really difficult problem to solve while also having a simple UX, so I'll live with it.
• I do wonder whether having a separate design repo is actually going to become more annoying in the agentic coding era. The design repo feels like it's got a lot of really useful context for Claude or similar. By having it in a separate repo from the code it's harder for newcomers to have their AI see all that context. It's also harder to keep aligned with the code itself. If we were to move the proposal process into kroxylicious/kroxylicious it would be easier, both for coding agents to see the context, but also to have help write proposals in tandem with the code.

[k-wall]

was wondering whether using PR number might be nicer. They'll still be chronological but then reffing #92 would also refer to proposal number 92.

I like this idea. It might be neater to have a separate proposals repo

[SamBarker]

@tombentley

I don't think there's really any value in maintaining a separate index

I think an index is worth having if it's cheap to maintain — and a GitHub Action that generates
it from the directory listing and open/closed PRs would make it essentially free.

I would value a way to keep the history of proposals that don't get accepted

Strongly agree. I think we should merge rejected proposals with a clear "rejected" status
regardless of what we do about numbering or indexing. That way the repo is the canonical
record of all proposals, not just the ones that succeeded. The discussion still lives on the
PR, but an auto-generated index that includes rejected proposals makes them discoverable
without having to know to go looking for a specific closed PR.

I do wonder whether having a separate design repo is actually going to become more annoying in the agentic coding era

I think we should stick with a separate repo. Agents can be pointed at multiple repos, and keeping
design discussion decoupled from implementation has value.

On @robobario's point about using PR numbers as proposal numbers — I like it in principle, but
there's a chicken-and-egg problem: you can't name the file after the PR number until the PR
exists, but you need the file to create the PR. So you'd either need a placeholder rename
after opening, or accept that the first commit always has a temporary name. That's not a
dealbreaker but it is a bit of friction — worth considering whether sequential allocation
(as this PR proposes, just automated) might be simpler in practice.

Either way, an auto-generated index would make the numbering scheme work without manual upkeep.

[k-wall]

I'm +1 to merging rejected proposals. We'd need our process to say that the proposal author updates the proposal with a summary why the proposal was rejected. We'd need a status on the proposal to reflect the fact that the proposal is rejected and a separate area on the summary page.

I can put together a GitHub action to auto maintain an index page.

We could probably have some automation to assign the next proposal number automatically (commenting on the PR), but this sounds like over engineering.

[tombentley]

@SamBarker

Agents can be pointed at multiple repos, and keeping
design discussion decoupled from implementation has value.

You're missing my point: It's about discoverability. People need to know about the other repo in the first place, clone it, and point their agent at it. Those are all barriers which need not exist. And the loss accrues to the project, because when people don't overcomes those barriers their agent has less context and will likely produce a worse result.

@k-wall

I'm +1 to merging rejected proposals. We'd need our process to say that the proposal author updates the proposal with a summary why the proposal was rejected. We'd need a status on the proposal to reflect the fact that the proposal is rejected and a separate area on the summary page.

You're assuming there is a point in time when it becomes clear that a proposal has been rejected, with obvious reasons why, and that when that occurs the proposal author will be motivated to actually be bothered to record the fact. I don't think any of those is actually true. It certainly seems to be the case for AK that:

• KIPs are almost never explicitly rejected; it's just that the discussion of them comes to a stop.
• But sometimes the conversation picks up some time later (sometimes months or years). So there is no obvious point in time where a KIP becomes rejected.
• And there might not be an obvious reason. Sometimes the comments make it clear, but sometimes it's as much an absence of engagement from sufficient committers that's the problem. How should that be summarised?
• Most people who are bothered to write a proposal will feel a little sad that their idea was not accepted. They went to some effort to write it all out, and engage with the discussion, and you're now asking them to publicly pore over their failure to get the idea accepted? I don't think a community that expects people to do that is terribly welcoming! Proposal discussions probably look like a hazing ritual already, let's not make it even less appealing.

So although I think it would be great if the project doesn't forget about the discussion of a proposal that's not accepted, I also don't think it's as simple as you're making out. It's not a only technical problem that just needs a little automation. It's as much a social problem.

[robobario]

You're missing my point: It's about discoverability. People need to know about the other repo in the first place, clone it, and point their agent at it. Those are all barriers which need not exist. And the loss accrues to the project, because when people don't overcomes those barriers their agent has less context and will likely produce a worse result.

Discoverability (of open proposals) would also be hurt by mingling Public API proposals with the wild amount of PRs in the main repo.

Maybe we could automatically sync the design repo contents on main push into a hidden directory of the kroxylicious repo via a PR.

You're assuming there is a point in time when it becomes clear that a proposal has been rejected

For now maybe we should put this problem to the side. Getting the workflow going for New + Accepted proposals and figuring out whether there is a Rejected flow later.

[tombentley]

Maybe we could automatically sync the design repo contents on main push into a hidden directory of the kroxylicious repo via a PR.

That might be worthwhile: Having the accepted proposals in the main repo is documenting the architecture and addresses the discoverability point.

Why does it need to be a hidden directory?

[k-wall]

You're missing my point: It's about discoverability. People need to know about the other repo in the first place, clone it, and point their agent at it. Those are all barriers which need not exist. And the loss accrues to the project, because when people don't overcomes those barriers their agent has less context and will likely produce a worse result.

Discoverability (of open proposals) would also be hurt by mingling Public API proposals with the wild amount of PRs in the main repo.

Maybe we could automatically sync the design repo contents on main push into a hidden directory of the kroxylicious repo via a PR.

You're assuming there is a point in time when it becomes clear that a proposal has been rejected

For now maybe we should put this problem to the side. Getting the workflow going for New + Accepted proposals and figuring out whether there is a Rejected flow later.

In order to make progress on the collision issue. I will do the following:

1. Raise a PR against the main repo to make the design proposal in this repo discoverable by the Claude running in a clone of the main repo. Should address Tom's discoverability point docs: add design proposals repository reference to help ensure Claude appreciates when a design proposal is required  kroxylicious#3794
2. Do away with the index part of this PR.
3. Adopt PR number is the Proposal number.
4. Add simple automation to check that new proposals adopt the PR number as their number.

[k-wall]

Closing in favor of #104 which has a cleaner implementation focused on automation.