This is an automated email from the ASF dual-hosted git repository.
hubcio pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iggy.git
The following commit(s) were added to refs/heads/master by this push:
new 3c4808944 chore(repo): improve issue/PR templates and trim triage docs
(#3372)
3c4808944 is described below
commit 3c4808944820337ef15b378212a543d0bba5ed1b
Author: Hubert Gruszecki <[email protected]>
AuthorDate: Fri May 29 13:20:28 2026 +0200
chore(repo): improve issue/PR templates and trim triage docs (#3372)
---
.github/ISSUE_TEMPLATE/bug_report.yml | 47 ++++++++++
.github/ISSUE_TEMPLATE/feature_request.yml | 34 ++++++-
.github/workflows/issue-labeler.yml | 105 +++++++++++++++++++++
.github/workflows/pr-triage-apply.yml | 11 +--
CONTRIBUTING.md | 145 ++++-------------------------
PULL_REQUEST_TEMPLATE.md | 7 +-
6 files changed, 209 insertions(+), 140 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml
b/.github/ISSUE_TEMPLATE/bug_report.yml
index dc8347522..c7682e070 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -32,6 +32,38 @@ body:
validations:
required: true
+ - type: dropdown
+ id: area
+ attributes:
+ label: Affected area / component
+ description: |
+ Which part(s) of the project does this affect? Your selection is
auto-labeled on the issue.
+ multiple: true
+ options:
+ - Iggy server
+ - Rust SDK
+ - Go SDK
+ - Java SDK
+ - Python SDK
+ - "C# SDK"
+ - Node.js SDK
+ - "C++ SDK"
+ - PHP SDK
+ - CLI
+ - Web UI
+ - Connectors
+ - MCP server
+ - Configuration
+ - Wire protocol / API
+ - Metadata
+ - Clustering / replication
+ - Performance
+ - Documentation
+ - CI / build / tooling
+ - Other / not sure
+ validations:
+ required: false
+
- type: dropdown
id: deployment
attributes:
@@ -102,3 +134,18 @@ body:
3. Observe ...
validations:
required: false
+
+ - type: checkboxes
+ id: contribution
+ attributes:
+ label: Contribution
+ options:
+ - label: I'm willing to submit a pull request to fix this bug
+
+ - type: checkboxes
+ id: good-first-issue
+ attributes:
+ label: Good first issue
+ description: A suggestion for triage; a maintainer decides whether to
apply the label.
+ options:
+ - label: I think this could be a good first issue for a new contributor
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml
b/.github/ISSUE_TEMPLATE/feature_request.yml
index 51f54294a..a6f83c461 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -34,10 +34,12 @@ body:
required: true
- type: dropdown
- id: component
+ id: area
attributes:
- label: Component
- description: Which part of the project does this affect?
+ label: Affected area / component
+ description: |
+ Which part(s) of the project does this affect? Your selection is
auto-labeled on the issue.
+ multiple: true
options:
- Iggy server
- Rust SDK
@@ -46,11 +48,20 @@ body:
- Python SDK
- "C# SDK"
- Node.js SDK
+ - "C++ SDK"
+ - PHP SDK
- CLI
- Web UI
- Connectors
+ - MCP server
+ - Configuration
+ - Wire protocol / API
+ - Metadata
+ - Clustering / replication
+ - Performance
- Documentation
- - Other
+ - CI / build / tooling
+ - Other / not sure
validations:
required: false
@@ -69,3 +80,18 @@ body:
description: Other approaches you thought of.
validations:
required: false
+
+ - type: checkboxes
+ id: contribution
+ attributes:
+ label: Contribution
+ options:
+ - label: I'm willing to submit a pull request to implement this feature
+
+ - type: checkboxes
+ id: good-first-issue
+ attributes:
+ label: Good first issue
+ description: A suggestion for triage; a maintainer decides whether to
apply the label.
+ options:
+ - label: I think this could be a good first issue for a new contributor
diff --git a/.github/workflows/issue-labeler.yml
b/.github/workflows/issue-labeler.yml
new file mode 100644
index 000000000..8b70c3249
--- /dev/null
+++ b/.github/workflows/issue-labeler.yml
@@ -0,0 +1,105 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: Issue Labeler
+
+# Maps the "Affected area / component" dropdown from the bug/feature issue
+# forms (.github/ISSUE_TEMPLATE/) onto real repo labels, so reporters who
+# lack triage permission still get their issue categorized at creation.
+#
+# Add-only by design: it never removes labels. Reporters rarely deselect,
+# and removing would fight maintainers who labeled by hand. addLabels is
+# idempotent, so re-running on `edited` is harmless.
+#
+# SECURITY: the issue body is attacker-controlled text, but it is parsed
+# only for exact matches against the fixed AREA_LABELS allowlist below, so
+# the only labels this workflow can ever apply are the ones listed here.
+# No checkout, no exec of issue contents, no token export.
+
+on:
+ issues:
+ types: [opened, edited]
+
+permissions:
+ issues: write
+ contents: read
+
+jobs:
+ label:
+ runs-on: ubuntu-24.04-arm
+ timeout-minutes: 5
+ steps:
+ - name: Apply area labels from issue form
+ uses: actions/github-script@v9
+ with:
+ script: |
+ // Dropdown option text -> repo label. Keep in sync with the
+ // `Affected area / component` options in
+ // .github/ISSUE_TEMPLATE/{bug_report,feature_request}.yml.
+ const AREA_LABELS = {
+ 'Iggy server': 'server',
+ 'Rust SDK': 'rust',
+ 'Go SDK': 'go',
+ 'Java SDK': 'java',
+ 'Python SDK': 'python',
+ 'C# SDK': 'csharp',
+ 'Node.js SDK': 'javascript',
+ 'C++ SDK': 'C++',
+ 'PHP SDK': 'php',
+ 'CLI': 'tui',
+ 'Web UI': 'web',
+ 'Connectors': 'connectors',
+ 'MCP server': 'mcp',
+ 'Configuration': 'config',
+ 'Wire protocol / API': 'api',
+ 'Metadata': 'metadata',
+ 'Clustering / replication': 'cluster',
+ 'Performance': 'performance',
+ 'Documentation': 'docs',
+ 'CI / build / tooling': 'CI/CD',
+ // 'Other / not sure' intentionally maps to no label.
+ };
+ const HEADING = 'Affected area / component';
+
+ const body = context.payload.issue.body || '';
+ // Issue-form bodies render as `### <label>\n\n<value>`; capture
+ // the dropdown's value block, up to the next `###` or the end.
+ const esc = HEADING.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ const section = body.match(
+ new RegExp('###[ \\t]+' + esc + '[
\\t]*\\n+([\\s\\S]*?)(?:\\n###|$)'),
+ );
+ // Multi-select renders the picks comma-separated on one line.
+ // Option text never contains a comma, so split on it safely.
+ const picks = (section ? section[1] : '')
+ .split(',')
+ .map(s => s.trim())
+ .filter(Boolean);
+ const labels = [...new Set(
+ picks.map(p => AREA_LABELS[p]).filter(Boolean),
+ )];
+
+ if (labels.length === 0) {
+ core.info('no mappable area selected, nothing to label');
+ return;
+ }
+ core.info(`applying labels: ${labels.join(', ')}`);
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.payload.issue.number,
+ labels,
+ });
diff --git a/.github/workflows/pr-triage-apply.yml
b/.github/workflows/pr-triage-apply.yml
index 7386ac1c4..2fa172c7a 100644
--- a/.github/workflows/pr-triage-apply.yml
+++ b/.github/workflows/pr-triage-apply.yml
@@ -221,15 +221,12 @@ jobs:
const WELCOME_MARKER = '<!-- iggy-pr-triage-welcome -->';
const WELCOME_BODY = [
WELCOME_MARKER,
- 'Thanks for the pull request. It is now waiting for review,
labeled `S-waiting-on-review`.',
+ 'Thanks for the PR. It is labeled `S-waiting-on-review` and
queued for review.',
'',
- 'You can update that label as the review goes back and forth,
with slash commands - each on its own line, in a regular PR comment (not an
inline review reply):',
+ 'Slash commands (own line, regular comment) move it around the
queue:',
'',
- '- `/ready` - mark it `S-waiting-on-review` again, after
addressing feedback',
- '- `/author` - mark it `S-waiting-on-author` (maintainers, or
anyone who has had a PR merged before)',
- '- `/request-review @user ...` - request reviewers (`@user` or
`@org/team`)',
- '',
- 'Commands take up to ~90s to apply. If no reaction (👍 or 😕)
appears on your comment, the apply step likely failed - check the repo\'s
Actions tab for the `PR Triage Apply` run. Commands posted inside a review body
(rather than a normal comment) cannot be reacted to, so they stay log-only.',
+ '- `/ready` - back to `S-waiting-on-review` after addressing
feedback',
+ '- `/request-review @user-or-team` - request a reviewer',
'',
'See
[CONTRIBUTING.md](https://github.com/apache/iggy/blob/master/CONTRIBUTING.md#pr-triage-commands)
for details.',
].join('\n');
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bf1928937..98155d8cd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,6 +32,12 @@ These require design discussion in the issue before coding:
Authors of PRs must run the code locally. "Relying on CI" is not acceptable.
+### Green CI
+
+Maintainers will not start reviewing a PR while its CI is failing. Get the
+pipeline green first - a red build, lint, or test means the PR is not ready
+for review.
+
### Single Purpose
One PR = one thing. Bug fix, refactor, feature - separate PRs. Mixed PRs will
be closed.
@@ -104,137 +110,22 @@ Keep subject under 72 chars. Use body for details if
needed.
## PR Triage Commands
-You can move a PR around the review queue by posting a slash command in the
-PR conversation. The pattern is similar to `rust-lang/triagebot`. The
-machinery lives in
-[`./.github/workflows/pr-triage-apply.yml`](./.github/workflows/pr-triage-apply.yml)
-(with a read-only collector in
-[`./.github/workflows/pr-triage-collect.yml`](./.github/workflows/pr-triage-collect.yml)
-that hops the token-permission gap for fork PRs) if you want to peek.
-
-### Commands
+Move a PR around the review queue by posting a slash command on its own
+line in a regular PR comment (not an inline review reply):
-| Command | Who can use it | What it does |
+| Command | Who | Effect |
| --- | --- | --- |
-| `/request-review @user-or-team ...` | the PR author or a maintainer |
Requests review from one or more `@user` or `@org/team` handles |
-| `/ready` | the PR author or a maintainer | Marks the PR
`S-waiting-on-review` |
-| `/author` | a maintainer, or any returning contributor (>=1 merged PR) |
Marks the PR `S-waiting-on-author` |
-
-A "maintainer" here means someone with write access to apache/iggy
-(in practice, the `@apache/iggy-committers` team). Automated comments from
-bots like Dependabot do not run commands.
-
-Each command has to start its own line. Leading whitespace is fine, but
-prose like `please /ready` will not match. You can put more than one command
-in a single comment: `/request-review` plus `/ready`, or `/request-review`
-plus `/author`. `/request-review` may carry several handles on one line and
-may also repeat across lines; all of them are collected and requested
-together. For `/ready` and `/author`, the last one wins, so `/ready` then
-`/author` in the same comment ends up as `S-waiting-on-author`.
-
-### Typical flow
-
-1. You open a PR. CODEOWNERS pings `@apache/iggy-committers` automatically.
-2. A maintainer reviews. Submitting a "Request changes" review moves the
- PR to your queue automatically; they can also comment `/author`.
-3. You push fixes, then comment `/ready`. The PR moves back to the review
- queue.
-4. Either side can comment `/request-review @somebody` to pull in a
- specific person or team.
-
-To find PRs waiting on review, filter with
-`is:open is:pr label:S-waiting-on-review` on the Pulls tab.
-
-### Lifecycle automation
-
-Some labels are managed for you based on what happens to the PR:
-
-| When | What happens |
-| --- | --- |
-| You open a PR (not a draft) | Gets `S-waiting-on-review`, unless an `S-*`
label is already set |
-| You mark a draft "Ready for review" | Gets `S-waiting-on-review`, unless an
`S-*` label is already set |
-| You convert the PR back to a draft | Both `S-*` labels are removed |
-| The PR is closed or merged | Both `S-*` labels are removed |
-
-Reopening a PR does not re-label it. Drop a `/ready` or `/author` comment
-to put it back in a queue.
-
-Drafts are skipped by the automatic labelling, but `/ready` and `/author`
-still work on drafts if you want to signal intent before clicking "Ready
-for review".
-
-### Review state
-
-Submitting a review with "Request changes" is treated as an implicit
-`/author`: the PR moves to `S-waiting-on-author`. Anyone GitHub recognizes
-as a repo contributor or above can trigger this - the same set that can
-issue an explicit `/author`. If your review body also contains an explicit
-`/ready` or `/author`, that command wins.
-
-### Tips
-
-- **One comment per command burst.** To request several reviewers at once,
- list them on a single `/request-review` line (or several lines) in one
- comment. Posting separate comments back-to-back can lose the middle one
- due to how CI runs are scheduled.
-- **Edits don't re-trigger.** If you typo a command and edit the comment, it
- will not run. Post a new comment instead.
-- **Use the main conversation, not inline review replies.** Commands posted
- as replies on a specific line of the diff are ignored. Post them in the
- PR's main comment thread.
-- **Suffixes don't match.** `/ready-to-merge` or `/readyish` will not flip
- state - only `/ready` followed by a space or end-of-line counts.
-
-### When something goes wrong
-
-Commands take up to ~90s to apply: the read-only collector hands the
-event off to the write-capable apply workflow via an artifact, which
-adds latency on top of GitHub Actions scheduling. Wait for a reaction
-before re-issuing - duplicate commands can interleave.
-
-The workflow reacts on your comment so you get quick feedback: a 👍 means
-a command was applied, a 😕 means a command was recognized but you lacked
-permission to run it. A failed `/request-review` also posts a one-line
-reply naming the handles GitHub rejected. Commands posted in a review body
-(rather than a normal comment) cannot be reacted to, so they stay
-log-only.
-
-If no reaction appears within a couple of minutes, the apply run likely
-failed. Open the repo's "Actions" tab and look at the `PR Triage Apply`
-run for the comment you posted - the run log says exactly what it saw
-and why (no permission, unknown user, transient API error, etc.). The
-`PR Triage Collect` run that appears on the PR's "Checks" tab is just
-the read-only event collector; the actual labelling happens in
-`PR Triage Apply`, which is triggered via `workflow_run` and is not
-attached to the PR's checks.
-
-### Examples
-
-Mark your PR ready after addressing feedback:
-
-```text
-/ready
-```
-
-Ask the author to take another look:
+| `/ready` | author or maintainer | mark `S-waiting-on-review` |
+| `/author` | maintainer or returning contributor | mark `S-waiting-on-author`
|
+| `/request-review @user-or-team ...` | author or maintainer | request review
from the listed `@user` / `@org/team` handles |
-```text
-/author
-```
+Some labels move on their own: opening or marking a non-draft PR ready sets
+`S-waiting-on-review`; a "Request changes" review sets `S-waiting-on-author`;
+closing or converting to draft clears both.
-Request a specific reviewer and mark ready in one comment:
-
-```text
-/request-review @somebody
-/ready
-```
-
-Request several reviewers in one go (do this instead of posting separate
-comments). They can share one line, span multiple lines, or both:
-
-```text
-/request-review @alice @bob @apache/iggy-committers
-```
+Commands take up to ~90s. A 👍 reaction means applied, 😕 means you lacked
+permission; if neither shows up, check the `PR Triage Apply` run in the
+Actions tab.
## Close Policy
diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
index 1d92178f0..4b3d82820 100644
--- a/PULL_REQUEST_TEMPLATE.md
+++ b/PULL_REQUEST_TEMPLATE.md
@@ -1,10 +1,13 @@
-## Which issue does this PR close?
+## Which issue does this PR address?
<!--
-We generally require a GitHub issue to be filed for all bug fixes and
enhancements. You can link an issue to this PR using the GitHub syntax. For
example `Closes #123` indicates that this PR will close issue #123.
+We generally require a GitHub issue for all bug fixes and enhancements. Link
it with GitHub syntax, keep the line that applies and delete the other:
+- `Closes #123` auto-closes the issue when this PR merges (full fix).
+- `Relates to #123` links without closing (partial or related work).
-->
Closes #
+Relates to #
## Rationale
