From f78133a9604bfaf98caedd490dc15a8fe484f19d Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Thu, 9 Apr 2026 11:41:06 +0100 Subject: [PATCH 1/2] Add proposals index and numbering process This introduces a proposal index (README.md) for the proposals directory to solve the problem of colliding proposal numbers. Currently, multiple open PRs have chosen proposal numbers that conflict with already-merged proposals. This creates confusion and makes it difficult to maintain stable identifiers for proposals - which is essential for productive discussion on the mailing list. The new process: 1. Authors create proposals with temporary filenames (nnn-*) 2. A separate PR to this README allocates the next sequential number 3. Authors rename their proposal once the number is allocated 4. The index is updated again when proposals are accepted This ensures: - Proposal numbers are allocated chronologically - No number collisions occur - Each proposal gets a stable identifier before mailing list discussion - Clear visibility of open vs. accepted proposals Current collisions resolved by this index: - PR #70, #82, #83, #88, #89 all have numbers conflicting with accepted proposals and have been allocated new sequential numbers (016-024) Assisted-By: Claude Sonnet 4.5 Signed-off-by: Keith Wall --- proposals/README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 proposals/README.md diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 0000000..83b3bfb --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,66 @@ +# Kroxylicious Proposals + +This repository lists proposals for the Kroxylicious project. + +## For Proposal Authors + +When creating a new proposal: + +1. Create your proposal PR with a temporary filename (e.g. `proposals/nnn-my-proposal.md`) based on the [template](./000-template.md). +2. After your proposal PR is created, raise a **separate PR** updating this README file to: + - Allocate your proposal the next sequential number + - Add an entry in the "Open Proposals" table below + - Link to your proposal PR + - Announce your proposal on the mailing list (https://kroxylicious.io/join-us/mailing-lists/) +3. Once the REAME PRs is merged, rename your proposal file to use the allocated number +4. When your proposal is approved and about to to be merged: + - Move your proposal from the "Open Proposals" table to the "Accepted Proposals" table + - Update the link to point to the merged file instead of the PR + +This process ensures proposal numbers are allocated in chronological order and avoids conflicts. + +## Open Proposals (Pull Requests) + +Proposals are numbered in chronological order by PR creation date. + +⚠️ **Note:** Some proposals have number collisions with accepted proposals and need to be renumbered: +- PR #70 (currently 004) → should be 016 +- PR #82 (currently 007) → should be 017 +- PR #83 (currently 012) → should be 018 +- PR #85 (currently nnn) → should be 019 +- PR #88 (currently 014) → should be 020 +- PR #89 (currently 016) → should be 021 +- PR #92 (currently xxx) → should be 022 +- PR #93 (currently xxx) → should be 023 +- PR #94 (currently nnn) → should be 024 + +| # | Title | PR | +|:--:|:----------------------------------------------------------------------|:--:| +| 24 | [Cleaning up TLS configurations](https://github.com/kroxylicious/design/pull/94) | [#94](https://github.com/kroxylicious/design/pull/94) | +| 23 | [Request/Response Contextual Data API](https://github.com/kroxylicious/design/pull/93) | [#93](https://github.com/kroxylicious/design/pull/93) | +| 22 | [Migrate Kroxylicious Operator to Strimzi v1 API](https://github.com/kroxylicious/design/pull/92) | [#92](https://github.com/kroxylicious/design/pull/92) | +| 21 | [Virtual Cluster Lifecycle](https://github.com/kroxylicious/design/pull/89) | [#89](https://github.com/kroxylicious/design/pull/89) ⚠️ | +| 20 | [Frontend Handler Refactoring & Client Session Context](https://github.com/kroxylicious/design/pull/88) | [#88](https://github.com/kroxylicious/design/pull/88) ⚠️ | +| 19 | [Audit logging](https://github.com/kroxylicious/design/pull/85) | [#85](https://github.com/kroxylicious/design/pull/85) | +| 18 | [Changing Active Proxy Configuration (Hot Reload)](https://github.com/kroxylicious/design/pull/83) | [#83](https://github.com/kroxylicious/design/pull/83) ⚠️ | +| 17 | [Kroxylicious 1.0 and patch releases](https://github.com/kroxylicious/design/pull/82) | [#82](https://github.com/kroxylicious/design/pull/82) ⚠️ | +| 16 | [A Routing API](https://github.com/kroxylicious/design/pull/70) | [#70](https://github.com/kroxylicious/design/pull/70) ⚠️ | + +## Accepted Proposals + +| # | Title | +|:--:|:----------------------------------------------------------------------| +| 15 | [Entity Isolation Filter](./015-entity-isolation.md) | +| 14 | [Restrict Operator to a Configurable Set of Namespaces](./014-operator-namespace-restriction.md) | +| 13 | [Upgrade Project JDK to Java 21](./013-upgrade-project-jdk-to-java-21.md) | +| 11 | [Plugin API for selecting TLS client credentials for proxy-to-server connection](./011-plugin-api-to-select-tls-credentials-for-server-connection.md) | +| 10 | [Extend the automatic discovery of bootstrap address feature to handle TLS listeners](./010-automatic-discovery-of-strimzi-bootstrap-server-tls.md) | +| 9 | [Authorization Filter](./009-authorizer.md) | +| 8 | [Resolve Topic Names from Topic IDs in the Filter Framework](./008-topic-name-lookup-facility.md) | +| 7 | [Azure KMS Implementation](./007-azure-kms.md) | +| 6 | [API to expose client SASL information to Filters](./006-filter-api-to-expose-client-sasl-info.md) | +| 5 | [Filter API to expose client and server TLS info](./005-filter-api-to-expose-client-and-server-tls-info.md) | +| 4 | [Terminology for Authentication](./004-terminology-for-authentication.md) | +| 3 | [Improvements to Kroxylicious (Proxy) Metrics](./003-metric-improvements.md) | +| 2 | [Automatically trigger a deployment rollout of affected proxies on Kubernetes config change](./002-Automaticly-reload-on-Kubernetes-config-change.md) | +| 1 | [Kroxylicious Operator API (v1alpha)](./001-kroxylicious-operator-api-v1alpha.md) | From 5a06b575e14ce364cd431fe7b6892644b38ca725 Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Fri, 24 Apr 2026 15:21:00 +0100 Subject: [PATCH 2/2] Implement PR-number-based proposal workflow This change simplifies the proposal numbering system by using PR numbers as proposal identifiers, eliminating number collisions and removing the need for a separate allocation process. Changes: - Simplified proposals/README.md to focus on author workflow - Removed index tables (directory listing serves as the index) - Streamlined instructions for creating and renaming proposals - Updated proposal template with workflow instructions - Added GitHub workflow to automatically check proposal numbering - Updates PR description when proposal files don't match PR number - Provides exact commands to fix naming issues - Removes warning once corrected - Added notification script for existing open PRs - After merge, run notify-open-prs.sh to ask authors to rebase - Workflow will automatically guide them through renaming Proposals 001-019 retain their original numbers. Co-Authored-By: Claude Sonnet 4.5 --- .github/workflows/proposal-numbering.yml | 171 +++++++++++++++++++++++ notify-open-prs.sh | 45 ++++++ proposals/000-template.md | 16 ++- proposals/README.md | 79 ++++------- 4 files changed, 256 insertions(+), 55 deletions(-) create mode 100644 .github/workflows/proposal-numbering.yml create mode 100755 notify-open-prs.sh diff --git a/.github/workflows/proposal-numbering.yml b/.github/workflows/proposal-numbering.yml new file mode 100644 index 0000000..2110a1a --- /dev/null +++ b/.github/workflows/proposal-numbering.yml @@ -0,0 +1,171 @@ +# +# Copyright Kroxylicious Authors. +# +# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0 +# + +# Automatically checks that proposal files follow the PR-number naming convention (e.g., proposals/092-my-proposal.md for PR #92). +# When a proposal file doesn't match its PR number, this workflow updates the PR description with instructions to rename it. +# Once the author fixes the naming, the warning is automatically removed from the PR description. + +name: Check Proposal Numbering + +on: + pull_request: + types: [opened, synchronize, reopened] + paths: + - 'proposals/*.md' + +permissions: + pull-requests: write + contents: read + +jobs: + check-numbering: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + fetch-depth: 0 + + - name: Check proposal file numbering + id: check + env: + PR_NUMBER: ${{ github.event.pull_request.number }} + run: | + # Find all .md files directly in proposals directory (not subdirectories) + ALL_PROPOSAL_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep '^proposals/[^/]*\.md$' || true) + + # Filter out non-proposal files (README.md and template) + PROPOSAL_FILES="" + for file in $ALL_PROPOSAL_FILES; do + # Skip README.md and the template + if [[ "$file" == "proposals/README.md" ]] || [[ "$file" == "proposals/000-template.md" ]]; then + continue + fi + PROPOSAL_FILES="$PROPOSAL_FILES $file" + done + + if [ -z "$PROPOSAL_FILES" ]; then + echo "No proposal files found in this PR" + echo "has_proposal=false" >> $GITHUB_OUTPUT + exit 0 + fi + + echo "has_proposal=true" >> $GITHUB_OUTPUT + + # Expected filename pattern: proposals/0{PR_NUMBER}-*.md + EXPECTED_PREFIX=$(printf "proposals/%03d-" $PR_NUMBER) + + INCORRECT_FILES="" + for file in $PROPOSAL_FILES; do + if [[ ! "$file" =~ ^${EXPECTED_PREFIX} ]]; then + if [ -z "$INCORRECT_FILES" ]; then + INCORRECT_FILES="$file" + else + INCORRECT_FILES="$INCORRECT_FILES,$file" + fi + fi + done + + if [ -n "$INCORRECT_FILES" ]; then + echo "incorrect=true" >> $GITHUB_OUTPUT + echo "files=$INCORRECT_FILES" >> $GITHUB_OUTPUT + echo "expected_prefix=$EXPECTED_PREFIX" >> $GITHUB_OUTPUT + else + echo "incorrect=false" >> $GITHUB_OUTPUT + fi + + - name: Update PR description if numbering is incorrect + if: steps.check.outputs.incorrect == 'true' + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + script: | + const prNumber = context.payload.pull_request.number; + const expectedPrefix = '${{ steps.check.outputs.expected_prefix }}'; + const incorrectFilesRaw = '${{ steps.check.outputs.files }}'; + + // Format files as markdown list + const filesList = incorrectFilesRaw.split(',').map(f => `- ${f}`).join('\n'); + + const warningSection = [ + '---', + '', + '## ⚠️ Proposal File Numbering', + '', + 'This PR contains proposal files that don\'t follow the expected numbering scheme:', + '', + filesList, + '', + `**Expected naming:** ${expectedPrefix}<descriptive-name>.md`, + '', + `Please rename your proposal file to use PR #${prNumber}:`, + '', + '```bash', + `git mv proposals/000-.md ${expectedPrefix}.md`, + '# or rename from current name to correct name', + `git commit -m "Rename proposal to use PR number ${prNumber}"`, + 'git push', + '```', + '', + 'See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the complete workflow.', + '', + '' + ].join('\n'); + + // Get current PR + const { data: pr } = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + }); + + let currentBody = pr.body || ''; + + // Remove existing warning section if present + const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal File Numbering[\s\S]*?/; + currentBody = currentBody.replace(markerRegex, '').trim(); + + // Append new warning section + const newBody = currentBody + '\n' + warningSection; + + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + body: newBody + }); + + - name: Remove warning from PR description if numbering is correct + if: steps.check.outputs.has_proposal == 'true' && steps.check.outputs.incorrect == 'false' + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + script: | + const prNumber = context.payload.pull_request.number; + + // Get current PR + const { data: pr } = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + }); + + let currentBody = pr.body || ''; + + // Check if warning section exists + const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal File Numbering[\s\S]*?/; + + if (markerRegex.test(currentBody)) { + // Remove warning section + const newBody = currentBody.replace(markerRegex, '').trim(); + + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + body: newBody + }); + + console.log('Removed numbering warning from PR description - file is now correctly named'); + } diff --git a/notify-open-prs.sh b/notify-open-prs.sh new file mode 100755 index 0000000..f930097 --- /dev/null +++ b/notify-open-prs.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# +# Copyright Kroxylicious Authors. +# +# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0 +# + +# Script to notify authors of open proposal PRs to rebase on main +# Once they rebase, the workflow will automatically check their proposal numbering + +set -e + +OPEN_PRS=(70 82 83 85 88 93 94) + +COMMENT_BODY="Hi! We've updated the proposal numbering system to use PR numbers as proposal identifiers. + +**Action required:** Please rebase your PR on \`main\`. + +Once you push, the GitHub workflow will automatically check your proposal file naming and update this PR description with specific instructions if your file needs to be renamed. + +See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the updated workflow." + +echo "This script will comment on ${#OPEN_PRS[@]} open proposal PRs" +echo "" +read -p "Continue? (y/N) " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Aborted" + exit 1 +fi + +for pr in "${OPEN_PRS[@]}"; do + echo "Commenting on PR #$pr..." + gh pr comment "$pr" --body "$COMMENT_BODY" + echo "✓ PR #$pr notified" + sleep 2 # Be nice to the API +done + +echo "" +echo "✓ All open proposal PRs have been notified" +echo "" +echo "Once authors rebase, the workflow will automatically:" +echo " 1. Detect if their proposal file naming is incorrect" +echo " 2. Update their PR description with the exact command to fix it" +echo " 3. Remove the warning once they fix the naming" diff --git a/proposals/000-template.md b/proposals/000-template.md index 538db1e..0088dc7 100644 --- a/proposals/000-template.md +++ b/proposals/000-template.md @@ -1,7 +1,21 @@ - + # +**Proposal**: #<PR-NUMBER> <!-- Update this after opening your PR --> + Provide a brief summary of the feature you are proposing to add to Kroxylicious. ## Current situation diff --git a/proposals/README.md b/proposals/README.md index 83b3bfb..48ded65 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -1,66 +1,37 @@ # Kroxylicious Proposals -This repository lists proposals for the Kroxylicious project. +This directory contains proposals for the Kroxylicious project. -## For Proposal Authors +## Creating a New Proposal -When creating a new proposal: +1. **Create your proposal file** using a placeholder name based on the [template](./000-template.md): + ``` + proposals/000-<descriptive-name>.md + ``` -1. Create your proposal PR with a temporary filename (e.g. `proposals/nnn-my-proposal.md`) based on the [template](./000-template.md). -2. After your proposal PR is created, raise a **separate PR** updating this README file to: - - Allocate your proposal the next sequential number - - Add an entry in the "Open Proposals" table below - - Link to your proposal PR - - Announce your proposal on the mailing list (https://kroxylicious.io/join-us/mailing-lists/) -3. Once the REAME PRs is merged, rename your proposal file to use the allocated number -4. When your proposal is approved and about to to be merged: - - Move your proposal from the "Open Proposals" table to the "Accepted Proposals" table - - Update the link to point to the merged file instead of the PR +2. **Commit and open a Pull Request**: + - Push your branch and open a PR on GitHub + - Note your PR number (e.g., #105) -This process ensures proposal numbers are allocated in chronological order and avoids conflicts. +3. **Rename the file** to use your PR number (three-digit zero-padded): + ```bash + git mv proposals/000-<descriptive-name>.md proposals/105-<descriptive-name>.md + git commit -m "Rename proposal to use PR number" + git push + ``` -## Open Proposals (Pull Requests) +4. **Announce** your proposal on the [mailing list](https://kroxylicious.io/join-us/mailing-lists/) -Proposals are numbered in chronological order by PR creation date. +When your proposal is **accepted and merged**, the proposal number remains the same as the PR number. -⚠️ **Note:** Some proposals have number collisions with accepted proposals and need to be renumbered: -- PR #70 (currently 004) → should be 016 -- PR #82 (currently 007) → should be 017 -- PR #83 (currently 012) → should be 018 -- PR #85 (currently nnn) → should be 019 -- PR #88 (currently 014) → should be 020 -- PR #89 (currently 016) → should be 021 -- PR #92 (currently xxx) → should be 022 -- PR #93 (currently xxx) → should be 023 -- PR #94 (currently nnn) → should be 024 +## Finding Proposals -| # | Title | PR | -|:--:|:----------------------------------------------------------------------|:--:| -| 24 | [Cleaning up TLS configurations](https://github.com/kroxylicious/design/pull/94) | [#94](https://github.com/kroxylicious/design/pull/94) | -| 23 | [Request/Response Contextual Data API](https://github.com/kroxylicious/design/pull/93) | [#93](https://github.com/kroxylicious/design/pull/93) | -| 22 | [Migrate Kroxylicious Operator to Strimzi v1 API](https://github.com/kroxylicious/design/pull/92) | [#92](https://github.com/kroxylicious/design/pull/92) | -| 21 | [Virtual Cluster Lifecycle](https://github.com/kroxylicious/design/pull/89) | [#89](https://github.com/kroxylicious/design/pull/89) ⚠️ | -| 20 | [Frontend Handler Refactoring & Client Session Context](https://github.com/kroxylicious/design/pull/88) | [#88](https://github.com/kroxylicious/design/pull/88) ⚠️ | -| 19 | [Audit logging](https://github.com/kroxylicious/design/pull/85) | [#85](https://github.com/kroxylicious/design/pull/85) | -| 18 | [Changing Active Proxy Configuration (Hot Reload)](https://github.com/kroxylicious/design/pull/83) | [#83](https://github.com/kroxylicious/design/pull/83) ⚠️ | -| 17 | [Kroxylicious 1.0 and patch releases](https://github.com/kroxylicious/design/pull/82) | [#82](https://github.com/kroxylicious/design/pull/82) ⚠️ | -| 16 | [A Routing API](https://github.com/kroxylicious/design/pull/70) | [#70](https://github.com/kroxylicious/design/pull/70) ⚠️ | +- **All proposals:** Browse the directory listing above +- **Open proposals:** [View open proposal PRs](https://github.com/kroxylicious/design/pulls?q=is%3Apr+is%3Aopen+label%3Aproposal) +- **Merged proposals:** Proposal files in this directory (sorted alphabetically) -## Accepted Proposals +## Numbering -| # | Title | -|:--:|:----------------------------------------------------------------------| -| 15 | [Entity Isolation Filter](./015-entity-isolation.md) | -| 14 | [Restrict Operator to a Configurable Set of Namespaces](./014-operator-namespace-restriction.md) | -| 13 | [Upgrade Project JDK to Java 21](./013-upgrade-project-jdk-to-java-21.md) | -| 11 | [Plugin API for selecting TLS client credentials for proxy-to-server connection](./011-plugin-api-to-select-tls-credentials-for-server-connection.md) | -| 10 | [Extend the automatic discovery of bootstrap address feature to handle TLS listeners](./010-automatic-discovery-of-strimzi-bootstrap-server-tls.md) | -| 9 | [Authorization Filter](./009-authorizer.md) | -| 8 | [Resolve Topic Names from Topic IDs in the Filter Framework](./008-topic-name-lookup-facility.md) | -| 7 | [Azure KMS Implementation](./007-azure-kms.md) | -| 6 | [API to expose client SASL information to Filters](./006-filter-api-to-expose-client-sasl-info.md) | -| 5 | [Filter API to expose client and server TLS info](./005-filter-api-to-expose-client-and-server-tls-info.md) | -| 4 | [Terminology for Authentication](./004-terminology-for-authentication.md) | -| 3 | [Improvements to Kroxylicious (Proxy) Metrics](./003-metric-improvements.md) | -| 2 | [Automatically trigger a deployment rollout of affected proxies on Kubernetes config change](./002-Automaticly-reload-on-Kubernetes-config-change.md) | -| 1 | [Kroxylicious Operator API (v1alpha)](./001-kroxylicious-operator-api-v1alpha.md) | +Proposal numbers match PR numbers, using three-digit zero-padding (e.g., `092-`, `105-`). + +Proposals 001-019 predate this system and retain their original numbers.