Skip to content

Commit 7c5f5f8

Browse files
k-wallk-wall
committed
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 - Require PR number in title format: # <PR#> - <Title> - Moved workflow instructions into comment block - Added GitHub workflow to automatically check proposal numbering - Validates both filename and title format - Updates PR description when proposal files don't match PR number - Provides exact commands to fix naming issues - Removes warning once corrected - Handles both added and renamed files - Runs on all PRs (ready for mandatory status check) - 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 - Updated with all current open proposal PRs (#70, #82, #83, #85, #88, #93, #94, #96, #98, #99, #100, #101, #103) Proposals 001-019 retain their original numbers. Assisted-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Keith Wall <kwall@apache.org>
1 parent e37f0be commit 7c5f5f8

4 files changed

Lines changed: 309 additions & 3 deletions

File tree

‎.github/workflows/proposal-numbering.yml‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
#
2+
# Copyright Kroxylicious Authors.
3+
#
4+
# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
5+
#
6+
7+
# Automatically checks that proposal files follow the PR-number naming convention (e.g., proposals/092-my-proposal.md for PR #92).
8+
# When a proposal file doesn't match its PR number, this workflow updates the PR description with instructions to rename it.
9+
# Once the author fixes the naming, the warning is automatically removed from the PR description.
10+
11+
name: Check Proposal Numbering
12+
13+
on:
14+
pull_request:
15+
types: [opened, synchronize, reopened]
16+
17+
permissions:
18+
pull-requests: write
19+
contents: read
20+
21+
jobs:
22+
check-numbering:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout code
26+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Check proposal file numbering
31+
id: check
32+
env:
33+
PR_NUMBER: ${{ github.event.pull_request.number }}
34+
run: |
35+
# Find all .md files directly in proposals directory (not subdirectories)
36+
# Include both Added (A) and Renamed (R) files
37+
ALL_PROPOSAL_FILES=$(git diff --name-only --diff-filter=AR origin/${{ github.base_ref }}...HEAD | grep '^proposals/[^/]*\.md$' || true)
38+
39+
# Filter out non-proposal files (README.md and template)
40+
PROPOSAL_FILES=""
41+
for file in $ALL_PROPOSAL_FILES; do
42+
# Skip README.md and the template
43+
if [[ "$file" == "proposals/README.md" ]] || [[ "$file" == "proposals/000-template.md" ]]; then
44+
continue
45+
fi
46+
PROPOSAL_FILES="$PROPOSAL_FILES $file"
47+
done
48+
49+
if [ -z "$PROPOSAL_FILES" ]; then
50+
echo "No proposal files found in this PR"
51+
echo "has_proposal=false" >> $GITHUB_OUTPUT
52+
exit 0
53+
fi
54+
55+
echo "has_proposal=true" >> $GITHUB_OUTPUT
56+
57+
# Expected filename pattern: proposals/0{PR_NUMBER}-*.md
58+
EXPECTED_PREFIX=$(printf "proposals/%03d-" $PR_NUMBER)
59+
60+
INCORRECT_FILES=""
61+
INCORRECT_TITLES=""
62+
for file in $PROPOSAL_FILES; do
63+
# Check filename
64+
if [[ ! "$file" =~ ^${EXPECTED_PREFIX} ]]; then
65+
if [ -z "$INCORRECT_FILES" ]; then
66+
INCORRECT_FILES="$file"
67+
else
68+
INCORRECT_FILES="$INCORRECT_FILES,$file"
69+
fi
70+
fi
71+
72+
# Check title format (should be: # <PR_NUMBER> - <Title>)
73+
EXPECTED_TITLE_PREFIX="# $PR_NUMBER -"
74+
if ! grep -q "^${EXPECTED_TITLE_PREFIX}" "$file"; then
75+
if [ -z "$INCORRECT_TITLES" ]; then
76+
INCORRECT_TITLES="$file"
77+
else
78+
INCORRECT_TITLES="$INCORRECT_TITLES,$file"
79+
fi
80+
fi
81+
done
82+
83+
if [ -n "$INCORRECT_FILES" ] || [ -n "$INCORRECT_TITLES" ]; then
84+
echo "incorrect=true" >> $GITHUB_OUTPUT
85+
echo "files=$INCORRECT_FILES" >> $GITHUB_OUTPUT
86+
echo "titles=$INCORRECT_TITLES" >> $GITHUB_OUTPUT
87+
echo "expected_prefix=$EXPECTED_PREFIX" >> $GITHUB_OUTPUT
88+
else
89+
echo "incorrect=false" >> $GITHUB_OUTPUT
90+
fi
91+
92+
- name: Update PR description if numbering is incorrect
93+
if: steps.check.outputs.incorrect == 'true'
94+
uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
95+
with:
96+
script: |
97+
const prNumber = context.payload.pull_request.number;
98+
const expectedPrefix = '${{ steps.check.outputs.expected_prefix }}';
99+
const incorrectFilesRaw = '${{ steps.check.outputs.files }}';
100+
const incorrectTitlesRaw = '${{ steps.check.outputs.titles }}';
101+
102+
const warnings = [];
103+
104+
// Check filename issues
105+
if (incorrectFilesRaw) {
106+
const filesList = incorrectFilesRaw.split(',').map(f => `- <code>${f}</code>`).join('\n');
107+
warnings.push(
108+
'**Incorrect filename:**',
109+
'',
110+
filesList,
111+
'',
112+
`**Expected naming:** <code>${expectedPrefix}&lt;descriptive-name&gt;.md</code>`,
113+
'',
114+
`Rename your proposal file to use PR #${prNumber}:`,
115+
'',
116+
'```bash',
117+
`git mv proposals/000-<name>.md ${expectedPrefix}<name>.md`,
118+
'```'
119+
);
120+
}
121+
122+
// Check title issues
123+
if (incorrectTitlesRaw) {
124+
const titlesList = incorrectTitlesRaw.split(',').map(f => `- <code>${f}</code>`).join('\n');
125+
if (warnings.length > 0) warnings.push('', '---', '');
126+
warnings.push(
127+
'**Incorrect title format:**',
128+
'',
129+
titlesList,
130+
'',
131+
`**Expected title format:** <code># ${prNumber} - &lt;Your Title&gt;</code>`,
132+
'',
133+
`Update the H1 heading in your proposal to include the PR number:`,
134+
'',
135+
'```markdown',
136+
`# ${prNumber} - My Feature Title`,
137+
'```'
138+
);
139+
}
140+
141+
const warningSection = [
142+
'---',
143+
'',
144+
'## ⚠️ Proposal Numbering',
145+
'',
146+
'This PR contains proposal files that don\'t follow the expected format:',
147+
'',
148+
...warnings,
149+
'',
150+
'See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the complete workflow.',
151+
'',
152+
'<!-- proposal-numbering-check -->'
153+
].join('\n');
154+
155+
// Get current PR
156+
const { data: pr } = await github.rest.pulls.get({
157+
owner: context.repo.owner,
158+
repo: context.repo.repo,
159+
pull_number: prNumber,
160+
});
161+
162+
let currentBody = pr.body || '';
163+
164+
// Remove existing warning section if present
165+
const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal (File )?Numbering[\s\S]*?<!-- proposal-numbering-check -->/;
166+
currentBody = currentBody.replace(markerRegex, '').trim();
167+
168+
// Append new warning section
169+
const newBody = currentBody + '\n' + warningSection;
170+
171+
await github.rest.pulls.update({
172+
owner: context.repo.owner,
173+
repo: context.repo.repo,
174+
pull_number: prNumber,
175+
body: newBody
176+
});
177+
178+
- name: Remove warning from PR description if numbering is correct
179+
if: steps.check.outputs.has_proposal == 'true' && steps.check.outputs.incorrect == 'false'
180+
uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
181+
with:
182+
script: |
183+
const prNumber = context.payload.pull_request.number;
184+
185+
// Get current PR
186+
const { data: pr } = await github.rest.pulls.get({
187+
owner: context.repo.owner,
188+
repo: context.repo.repo,
189+
pull_number: prNumber,
190+
});
191+
192+
let currentBody = pr.body || '';
193+
194+
// Check if warning section exists
195+
const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal (File )?Numbering[\s\S]*?<!-- proposal-numbering-check -->/;
196+
197+
if (markerRegex.test(currentBody)) {
198+
// Remove warning section
199+
const newBody = currentBody.replace(markerRegex, '').trim();
200+
201+
await github.rest.pulls.update({
202+
owner: context.repo.owner,
203+
repo: context.repo.repo,
204+
pull_number: prNumber,
205+
body: newBody
206+
});
207+
208+
console.log('Removed numbering warning from PR description - file is now correctly named');
209+
}

‎notify-open-prs.sh‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
#!/bin/bash
2+
#
3+
# Copyright Kroxylicious Authors.
4+
#
5+
# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
6+
#
7+
8+
# Script to notify authors of open proposal PRs to rebase on main
9+
# Once they rebase, the workflow will automatically check their proposal numbering
10+
11+
set -e
12+
13+
OPEN_PRS=(70 82 83 85 88 93 94 96 98 99 100 101 103)
14+
15+
COMMENT_BODY="Hi! We've updated the proposal numbering system to use PR numbers as proposal identifiers.
16+
17+
**Action required:** Please rebase your PR on \`main\`.
18+
19+
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.
20+
21+
See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the updated workflow."
22+
23+
echo "This script will comment on ${#OPEN_PRS[@]} open proposal PRs"
24+
echo ""
25+
read -p "Continue? (y/N) " -n 1 -r
26+
echo
27+
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
28+
echo "Aborted"
29+
exit 1
30+
fi
31+
32+
for pr in "${OPEN_PRS[@]}"; do
33+
echo "Commenting on PR #$pr..."
34+
gh pr comment "$pr" --body "$COMMENT_BODY"
35+
echo "✓ PR #$pr notified"
36+
sleep 2 # Be nice to the API
37+
done
38+
39+
echo ""
40+
echo "✓ All open proposal PRs have been notified"
41+
echo ""
42+
echo "Once authors rebase, the workflow will automatically:"
43+
echo " 1. Detect if their proposal file naming is incorrect"
44+
echo " 2. Update their PR description with the exact command to fix it"
45+
echo " 3. Remove the warning once they fix the naming"

‎proposals/000-template.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
1-
<!-- This template is provided as an example with sections you may wish to comment on with respect to your proposal. Add or remove sections as required to best articulate the proposal. -->
2-
3-
# <Title>
1+
<!--
2+
PROPOSAL WORKFLOW:
3+
1. Copy this template to: proposals/000-<descriptive-name>.md
4+
2. Fill in your proposal content
5+
3. Open a PR on GitHub
6+
4. Rename the file to use your PR number: proposals/<PR#>-<descriptive-name>.md
7+
Example: git mv proposals/000-my-feature.md proposals/105-my-feature.md
8+
5. Update the heading below to include your PR number: # <PR#> - <Title>
9+
6. Push the rename and updated title to your PR
10+
11+
See proposals/README.md for complete instructions.
12+
13+
This template is provided as an example with sections you may wish to comment on with respect to your proposal. Add or remove sections as required to best articulate the proposal.
14+
-->
15+
16+
# <PR-NUMBER> - <Title>
417

518
Provide a brief summary of the feature you are proposing to add to Kroxylicious.
619

‎proposals/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Kroxylicious Proposals
2+
3+
This directory contains proposals for the Kroxylicious project.
4+
5+
## Creating a New Proposal
6+
7+
1. **Create your proposal file** using a placeholder name based on the [template](./000-template.md):
8+
```
9+
cp proposals/000-template.md proposals/000-<descriptive-name>.md
10+
```
11+
12+
2. **Commit and open a Pull Request**:
13+
- Push your branch and open a PR on GitHub
14+
- Note your PR number (e.g., #105)
15+
16+
3. **Rename the file and update the title** to use your PR number (three-digit zero-padded):
17+
```bash
18+
git mv proposals/000-<descriptive-name>.md proposals/105-<descriptive-name>.md
19+
# Edit the file to update the title to: # 105 - <Your Title>
20+
git commit -m "Rename proposal to use PR number"
21+
git push
22+
```
23+
24+
4. **Announce** your proposal on the [mailing list](https://kroxylicious.io/join-us/mailing-lists/)
25+
26+
5. **Discussion and approval**: The proposal will be discussed by the community
27+
28+
6. **Merge**: Once approved, your proposal PR is merged to main. The proposal number remains the same as the PR number.
29+
30+
## Finding Proposals
31+
32+
- **Merged proposals:** Browse the directory listing above
33+
- **Open proposals:** [View open proposal PRs](https://github.com/kroxylicious/design/pulls?q=is%3Apr+is%3Aopen)
34+
35+
## Numbering
36+
37+
Proposal numbers match PR numbers, using three-digit zero-padding (e.g., `092-`, `105-`).
38+
39+
Proposals 001-019 predate this system and retain their original numbers.

0 commit comments

Comments
 (0)