From 030941fc8312ecaeeb0873cb92344c6e5b711882 Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Fri, 24 Apr 2026 15:21:00 +0100 Subject: [PATCH 1/4] 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 MIGRATION_GUIDE.md with specific instructions for open PRs Proposals 001-019 retain their original numbers. Co-Authored-By: Claude Sonnet 4.5 --- .github/workflows/proposal-numbering.yml | 155 +++++++++++++++++++++++ MIGRATION_GUIDE.md | 109 ++++++++++++++++ proposals/000-template.md | 16 ++- proposals/README.md | 79 ++++-------- 4 files changed, 304 insertions(+), 55 deletions(-) create mode 100644 .github/workflows/proposal-numbering.yml create mode 100644 MIGRATION_GUIDE.md diff --git a/.github/workflows/proposal-numbering.yml b/.github/workflows/proposal-numbering.yml new file mode 100644 index 00000000..a4c52606 --- /dev/null +++ b/.github/workflows/proposal-numbering.yml @@ -0,0 +1,155 @@ +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@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 + INCORRECT_FILES="$INCORRECT_FILES\n- \`$file\`" + fi + done + + if [ -n "$INCORRECT_FILES" ]; then + echo "incorrect=true" >> $GITHUB_OUTPUT + echo "files<> $GITHUB_OUTPUT + echo -e "$INCORRECT_FILES" >> $GITHUB_OUTPUT + echo "EOF" >> $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@v7 + with: + script: | + const prNumber = context.payload.pull_request.number; + const expectedPrefix = '${{ steps.check.outputs.expected_prefix }}'; + const incorrectFiles = `${{ steps.check.outputs.files }}`; + + const warningSection = ` + --- + + ## ⚠️ Proposal File Numbering + + This PR contains proposal files that don't follow the expected numbering scheme: + + ${incorrectFiles} + + **Expected naming:** \`${expectedPrefix}.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. + + `; + + // 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@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/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 00000000..5b582a9c --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,109 @@ +# Proposal Numbering Migration Guide + +This guide contains the migration instructions for existing open proposal PRs to adopt the new PR-number-based numbering system. + +## Background + +We've adopted a new proposal numbering system where proposal numbers match their PR numbers. This eliminates collisions and simplifies the workflow. + +## Migration Instructions by PR + +### PR #70 - Routing API +**Current file:** `proposals/004-routing-api.md` +**New file:** `proposals/070-routing-api.md` + +```bash +git mv proposals/004-routing-api.md proposals/070-routing-api.md +git commit -m "Rename proposal to use PR number 70" +git push +``` + +### PR #82 - Kroxylicious 1.0 +**Current file:** `proposals/007-kroxylicious-1.0.md` +**New file:** `proposals/082-kroxylicious-1.0.md` + +```bash +git mv proposals/007-kroxylicious-1.0.md proposals/082-kroxylicious-1.0.md +git commit -m "Rename proposal to use PR number 82" +git push +``` + +### PR #83 - Hot Reload Feature +**Current file:** `proposals/012-hot-reload-feature.md` +**New file:** `proposals/083-hot-reload-feature.md` + +```bash +git mv proposals/012-hot-reload-feature.md proposals/083-hot-reload-feature.md +git commit -m "Rename proposal to use PR number 83" +git push +``` + +### PR #85 - Audit Logging +**Current file:** `proposals/nnn-audit-logging.md` +**New file:** `proposals/085-audit-logging.md` + +```bash +git mv proposals/nnn-audit-logging.md proposals/085-audit-logging.md +git commit -m "Rename proposal to use PR number 85" +git push +``` + +### PR #88 - Frontend Handler Refactoring +**Current file:** `proposals/014-frontend-handler-refactoring-and-centralised-session-context.md` +**New file:** `proposals/088-frontend-handler-refactoring-and-centralised-session-context.md` + +```bash +git mv proposals/014-frontend-handler-refactoring-and-centralised-session-context.md proposals/088-frontend-handler-refactoring-and-centralised-session-context.md +git commit -m "Rename proposal to use PR number 88" +git push +``` + +### PR #93 - Correlated Request/Response Data API +**Current file:** `proposals/xxx-correlated-request-response-data-api.md` +**New file:** `proposals/093-correlated-request-response-data-api.md` + +```bash +git mv proposals/xxx-correlated-request-response-data-api.md proposals/093-correlated-request-response-data-api.md +git commit -m "Rename proposal to use PR number 93" +git push +``` + +### PR #94 - TLS Configuration Deprecation +**Current file:** `proposals/nnn-tls-configuration.md` +**New file:** `proposals/094-tls-configuration.md` + +```bash +git mv proposals/nnn-tls-configuration.md proposals/094-tls-configuration.md +git commit -m "Rename proposal to use PR number 94" +git push +``` + +## Comment Template for PR Authors + +Use this template to comment on each PR: + +--- + +Hi! We've updated the proposal numbering system to use PR numbers instead of sequential allocation. This eliminates number collisions and simplifies the workflow. + +**Action required:** Please rename your proposal file to use this PR's number. + +**Current file:** `proposals/XXX-name.md` +**New file:** `proposals/0YY-name.md` + +```bash +git mv proposals/XXX-name.md proposals/0YY-name.md +git commit -m "Rename proposal to use PR number YY" +git push +``` + +See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the updated workflow. Going forward, a GitHub Action will automatically remind you if the filename doesn't match the PR number. + +--- + +## After Migration + +Once all open PRs have been renamed: +- The GitHub workflow will automatically check new proposals +- No manual index maintenance is needed - the directory listing is the index +- Proposal numbers will match PR numbers going forward diff --git a/proposals/000-template.md b/proposals/000-template.md index 538db1e4..0088dc73 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 83b3bfb1..48ded65e 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. From 87c1f62fb2daa088b733b40aff770c7e02d13b03 Mon Sep 17 00:00:00 2001 From: Keith Wall <kwall@apache.org> Date: Fri, 24 Apr 2026 15:35:49 +0100 Subject: [PATCH 2/4] Add test proposal with incorrect numbering --- .github/workflows/proposal-numbering.yml | 64 +++++++++++++----------- proposals/000-test-workflow.md | 12 +++++ 2 files changed, 47 insertions(+), 29 deletions(-) create mode 100644 proposals/000-test-workflow.md diff --git a/.github/workflows/proposal-numbering.yml b/.github/workflows/proposal-numbering.yml index a4c52606..069ebe2e 100644 --- a/.github/workflows/proposal-numbering.yml +++ b/.github/workflows/proposal-numbering.yml @@ -51,15 +51,17 @@ jobs: INCORRECT_FILES="" for file in $PROPOSAL_FILES; do if [[ ! "$file" =~ ^${EXPECTED_PREFIX} ]]; then - INCORRECT_FILES="$INCORRECT_FILES\n- \`$file\`" + 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<<EOF" >> $GITHUB_OUTPUT - echo -e "$INCORRECT_FILES" >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT + echo "files=$INCORRECT_FILES" >> $GITHUB_OUTPUT echo "expected_prefix=$EXPECTED_PREFIX" >> $GITHUB_OUTPUT else echo "incorrect=false" >> $GITHUB_OUTPUT @@ -72,31 +74,35 @@ jobs: script: | const prNumber = context.payload.pull_request.number; const expectedPrefix = '${{ steps.check.outputs.expected_prefix }}'; - const incorrectFiles = `${{ steps.check.outputs.files }}`; - - const warningSection = ` - --- - - ## ⚠️ Proposal File Numbering - - This PR contains proposal files that don't follow the expected numbering scheme: - - ${incorrectFiles} - - **Expected naming:** \`${expectedPrefix}<descriptive-name>.md\` - - Please rename your proposal file to use PR #${prNumber}: - - \`\`\`bash - git mv proposals/000-<name>.md ${expectedPrefix}<name>.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. - - <!-- proposal-numbering-check -->`; + const incorrectFilesRaw = '${{ steps.check.outputs.files }}'; + + // Format files as markdown list + const filesList = incorrectFilesRaw.split(',').map(f => `- <code>${f}</code>`).join('\n'); + + const warningSection = [ + '---', + '', + '## ⚠️ Proposal File Numbering', + '', + 'This PR contains proposal files that don\'t follow the expected numbering scheme:', + '', + filesList, + '', + `**Expected naming:** <code>${expectedPrefix}<descriptive-name>.md</code>`, + '', + `Please rename your proposal file to use PR #${prNumber}:`, + '', + '```bash', + `git mv proposals/000-<name>.md ${expectedPrefix}<name>.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.', + '', + '<!-- proposal-numbering-check -->' + ].join('\n'); // Get current PR const { data: pr } = await github.rest.pulls.get({ diff --git a/proposals/000-test-workflow.md b/proposals/000-test-workflow.md new file mode 100644 index 00000000..cccefc05 --- /dev/null +++ b/proposals/000-test-workflow.md @@ -0,0 +1,12 @@ +# Test Proposal for Workflow + +**Proposal**: #TBD + +This is a test proposal to verify the GitHub workflow correctly detects incorrect proposal numbering and updates the PR description. + +## Purpose + +Verify that: +1. The workflow detects this file (starts with 000-) +2. The workflow updates the PR description with a warning +3. The workflow provides the correct renaming command From 4f899db88610457b423e82430ff3cfd277872bfb Mon Sep 17 00:00:00 2001 From: Keith Wall <kwall@apache.org> Date: Fri, 24 Apr 2026 15:39:19 +0100 Subject: [PATCH 3/4] Update test proposal to trigger workflow --- proposals/000-test-workflow.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/000-test-workflow.md b/proposals/000-test-workflow.md index cccefc05..a0a59f1e 100644 --- a/proposals/000-test-workflow.md +++ b/proposals/000-test-workflow.md @@ -10,3 +10,4 @@ Verify that: 1. The workflow detects this file (starts with 000-) 2. The workflow updates the PR description with a warning 3. The workflow provides the correct renaming command +4. HTML entities are used instead of backticks (cleaner syntax) From 576bc3f31fa933f912179e95abd066192d5552d9 Mon Sep 17 00:00:00 2001 From: Keith Wall <kwall@apache.org> Date: Fri, 24 Apr 2026 15:42:35 +0100 Subject: [PATCH 4/4] Rename proposal to use PR number 2 --- proposals/{000-test-workflow.md => 002-test-workflow.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{000-test-workflow.md => 002-test-workflow.md} (100%) diff --git a/proposals/000-test-workflow.md b/proposals/002-test-workflow.md similarity index 100% rename from proposals/000-test-workflow.md rename to proposals/002-test-workflow.md