Skip to content

Commit b365bbc

Browse files
MarkusNeusingerclaude
MarkusNeusinger
and
claude
authored
feat: add report issue system for specs and implementations (#3285)
## Summary - Add structured system for reporting issues with specs and implementations - Rename issue templates from `plot-*.yml` to `spec-*.yml` for consistency - Add frontend links for "suggest spec" (catalog) and "report issue" (spec pages) - Responsive design: icon on mobile, text on desktop ## Changes - **Issue Templates:** New `report-issue.yml`, renamed `spec-request.yml` and `spec-update.yml` - **Workflow:** `report-validate.yml` for AI-powered issue analysis - **Frontend:** Breadcrumb links in CatalogPage and SpecPage - **Documentation:** Updated contributing.md, README.md, added report-issue.md ## Test plan - [ ] Verify "suggest spec" link appears in catalog breadcrumb - [ ] Verify "report issue" link appears in spec page breadcrumb - [ ] Test responsive behavior (icon on mobile xs/sm, text on md+) - [ ] Check GitHub issue templates are available 🤖 Generated with [Claude Code](https://claude.ai/code) --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 6250d88 commit b365bbc

File tree

14 files changed

+766
-149
lines changed

14 files changed

+766
-149
lines changed

‎.github/ISSUE_TEMPLATE/report-issue.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Report Issue
2+
description: Report an issue with an existing plot spec or implementation
3+
title: "Report: "
4+
labels: ["report-pending"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
## Report an Issue
10+
11+
Found a problem with an existing plot? Let us know!
12+
13+
Our AI will validate and structure your report, then queue it for maintainer review.
14+
15+
- type: input
16+
id: spec_id
17+
attributes:
18+
label: Specification ID
19+
description: "The spec ID of the affected plot"
20+
placeholder: "e.g., scatter-basic, qrcode-basic, heatmap-correlation"
21+
validations:
22+
required: true
23+
24+
- type: dropdown
25+
id: target
26+
attributes:
27+
label: What has the issue?
28+
description: "Is this an issue with the specification itself or a specific library implementation?"
29+
options:
30+
- Specification (affects all libraries)
31+
- Implementation (specific library)
32+
validations:
33+
required: true
34+
35+
- type: dropdown
36+
id: library
37+
attributes:
38+
label: Library (only for implementation issues)
39+
description: "Which library implementation has the issue? Select N/A for spec issues."
40+
options:
41+
- N/A (spec issue)
42+
- matplotlib
43+
- seaborn
44+
- plotly
45+
- bokeh
46+
- altair
47+
- plotnine
48+
- pygal
49+
- highcharts
50+
- letsplot
51+
validations:
52+
required: false
53+
54+
- type: dropdown
55+
id: category
56+
attributes:
57+
label: Issue Category
58+
description: "What type of issue is this?"
59+
options:
60+
- Visual (ugly, unclear, hard to read)
61+
- Data (unrealistic values, inappropriate context)
62+
- Functional (doesn't work as expected, e.g., QR code not scannable)
63+
- Other
64+
validations:
65+
required: true
66+
67+
- type: textarea
68+
id: description
69+
attributes:
70+
label: Issue Description
71+
description: "Describe the issue. What's wrong? What should it look like instead?"
72+
placeholder: |
73+
Example: The QR code generated looks like a QR code but cannot be scanned by any QR reader app.
74+
75+
Expected: The QR code should be a valid, scannable code that links to the specified URL.
76+
validations:
77+
required: true
78+
79+
- type: textarea
80+
id: additional
81+
attributes:
82+
label: Additional Context (optional)
83+
description: "Screenshots, comparison images, or other helpful information"
84+
validations:
85+
required: false

.github/ISSUE_TEMPLATE/plot-request.yml renamed to .github/ISSUE_TEMPLATE/spec-request.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: Plot Request
22
description: Propose a new plot type for pyplots
3-
labels: ["plot-request"]
3+
labels: ["spec-request"]
44
body:
55
- type: markdown
66
attributes:

.github/ISSUE_TEMPLATE/plot-update.yml renamed to .github/ISSUE_TEMPLATE/spec-update.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name: Plot Update
22
description: Request updates or regeneration of an existing plot
33
title: "[SPEC-ID] [update] "
4-
labels: ["plot-request", "update"]
4+
labels: ["spec-update"]
55
body:
66
- type: markdown
77
attributes:

‎.github/workflows/report-validate.yml‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
name: "Report: Validate"
2+
run-name: "Validate Report: ${{ github.event.issue.title }}"
3+
4+
# Validates and structures user-submitted issue reports
5+
# Flow:
6+
# 1. User submits report → report-pending label auto-added
7+
# 2. AI validates spec/impl exists, analyzes issue, posts structured comment
8+
# 3. Labels updated: report-validated + category + report:spec/impl
9+
10+
on:
11+
issues:
12+
types: [labeled]
13+
14+
concurrency:
15+
group: report-validate-${{ github.event.issue.number }}
16+
cancel-in-progress: false
17+
18+
jobs:
19+
validate:
20+
if: github.event.label.name == 'report-pending'
21+
runs-on: ubuntu-latest
22+
permissions:
23+
contents: read
24+
issues: write
25+
26+
steps:
27+
- name: Check if already validated
28+
id: check
29+
env:
30+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
31+
run: |
32+
# Check if already has report-validated label
33+
LABELS=$(gh issue view ${{ github.event.issue.number }} --json labels -q '.labels[].name' | tr '\n' ' ')
34+
if echo "$LABELS" | grep -q "report-validated"; then
35+
echo "::notice::Skipping: Issue already validated"
36+
echo "should_run=false" >> $GITHUB_OUTPUT
37+
exit 0
38+
fi
39+
echo "should_run=true" >> $GITHUB_OUTPUT
40+
41+
- name: Checkout repository
42+
if: steps.check.outputs.should_run == 'true'
43+
uses: actions/checkout@v6
44+
45+
- name: React with eyes emoji
46+
if: steps.check.outputs.should_run == 'true'
47+
env:
48+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
49+
run: |
50+
gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \
51+
-f content=eyes
52+
53+
- name: Validate with Claude
54+
if: steps.check.outputs.should_run == 'true'
55+
id: validate
56+
continue-on-error: true
57+
timeout-minutes: 10
58+
uses: anthropics/claude-code-action@v1
59+
with:
60+
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
61+
claude_args: "--model sonnet"
62+
prompt: |
63+
## Task: Validate Issue Report
64+
65+
You are validating a user-submitted issue report for pyplots.
66+
67+
### Issue Details
68+
- **Title:** ${{ github.event.issue.title }}
69+
- **Number:** #${{ github.event.issue.number }}
70+
- **Author:** ${{ github.event.issue.user.login }}
71+
- **Body:**
72+
```
73+
${{ github.event.issue.body }}
74+
```
75+
76+
---
77+
78+
## Instructions
79+
80+
1. **Read the prompt:** `prompts/workflow-prompts/report-analysis.md`
81+
82+
2. **Parse the issue body** to extract:
83+
- spec_id (from "Specification ID" field)
84+
- target (Specification or Implementation)
85+
- library (if implementation)
86+
- category (Visual/Data/Functional/Other)
87+
- description
88+
89+
3. **Validate the spec exists:**
90+
```bash
91+
ls plots/{spec_id}/
92+
```
93+
If NOT found:
94+
- Post comment: "Spec `{spec_id}` not found. Please check the ID."
95+
- Remove `report-pending` label
96+
- Close issue
97+
- STOP
98+
99+
4. **If implementation issue, validate the library exists:**
100+
```bash
101+
ls plots/{spec_id}/implementations/{library}.py
102+
```
103+
If NOT found:
104+
- Post comment: "Implementation `{library}` not found for `{spec_id}`."
105+
- Remove `report-pending` label
106+
- Close issue
107+
- STOP
108+
109+
5. **Read relevant files:**
110+
- `plots/{spec_id}/specification.md`
111+
- `plots/{spec_id}/metadata/{library}.yaml` (if impl issue)
112+
113+
6. **Post structured analysis comment** following the format in the prompt file.
114+
115+
7. **Update issue title:**
116+
```bash
117+
gh issue edit ${{ github.event.issue.number }} --title "[{spec_id}] {brief description}"
118+
```
119+
120+
8. **Update labels:**
121+
```bash
122+
# Remove pending, add validated
123+
gh issue edit ${{ github.event.issue.number }} --remove-label "report-pending" --add-label "report-validated"
124+
125+
# Add target label
126+
gh issue edit ${{ github.event.issue.number }} --add-label "report:spec"
127+
# OR for impl:
128+
gh issue edit ${{ github.event.issue.number }} --add-label "report:impl" --add-label "report:impl:{library}"
129+
130+
# Add category label (map from dropdown value)
131+
# Visual → category:visual
132+
# Data → category:data
133+
# Functional → category:functional
134+
# Other → category:other
135+
gh issue edit ${{ github.event.issue.number }} --add-label "category:{category}"
136+
```
137+
138+
### Important
139+
- Do NOT add the `approved` label
140+
- Do NOT trigger any fixes
141+
- Keep the analysis comment concise but informative
142+
143+
- name: Add reaction on success
144+
if: steps.check.outputs.should_run == 'true' && steps.validate.outcome == 'success'
145+
env:
146+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
147+
run: |
148+
gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \
149+
-f content=rocket
150+
151+
- name: Handle failure
152+
if: steps.check.outputs.should_run == 'true' && steps.validate.outcome == 'failure'
153+
env:
154+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
155+
run: |
156+
gh issue comment ${{ github.event.issue.number }} --body "## :x: Validation Failed
157+
158+
The AI validation workflow encountered an error. A maintainer will review this manually.
159+
160+
---
161+
:robot: *[report-validate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
162+
163+
gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \
164+
-f content=confused

‎CLAUDE.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -618,6 +618,12 @@ Located in `.github/workflows/`:
618618
| **impl-merge.yml** | `ai-approved` label OR workflow_dispatch | Merges approved PR, creates metadata/{library}.yaml |
619619
| **bulk-generate.yml** | workflow_dispatch only | Dispatches multiple implementations (max 3 parallel) |
620620

621+
### Report Workflows (`report-*.yml`)
622+
623+
| Workflow | Trigger | Purpose |
624+
|----------|---------|---------|
625+
| **report-validate.yml** | `report-pending` label | Validates and structures user-submitted issue reports |
626+
621627
### Workflow Data Flow
622628

623629
**Flow A: New Specification (with approval gate)**
@@ -674,6 +680,29 @@ impl-review.yml
674680
└── Re-triggers impl-review.yml
675681
```
676682
683+
**Flow C: Report Issue**
684+
685+
```
686+
User submits report issue (from pyplots.ai or GitHub)
687+
│
688+
▼ (report-pending label auto-added)
689+
│
690+
report-validate.yml
691+
├── Validates spec/impl exists
692+
├── Reads specification and metadata
693+
├── AI analyzes the issue
694+
├── Posts structured analysis comment
695+
├── Updates title: [{spec-id}] {brief description}
696+
└── Updates labels: report-validated + category:* + report:spec/impl
697+
│
698+
▼
699+
Issue ready for maintainer review
700+
│
701+
▼ (maintainer adds `approved` label)
702+
│
703+
(Fix workflow - future implementation)
704+
```
705+
677706
### Supporting Workflows
678707
679708
| Workflow | Purpose |
@@ -757,6 +786,20 @@ These are set automatically by `impl-review.yml` after AI evaluation and used by
757786
- **`documentation`** - Documentation improvements
758787
- **`enhancement`** - New feature or improvement
759788

789+
### Report Labels
790+
791+
| Label | Purpose |
792+
|-------|---------|
793+
| `report:spec` | Issue with the specification (affects all libraries) |
794+
| `report:impl` | Issue with a specific implementation |
795+
| `report:impl:{library}` | Specific library affected (e.g., `report:impl:matplotlib`) |
796+
| `category:visual` | Design/visual issues |
797+
| `category:data` | Data quality issues |
798+
| `category:functional` | Non-functional elements |
799+
| `category:other` | Other issues |
800+
| `report-pending` | Report submitted, awaiting AI validation |
801+
| `report-validated` | AI validated, ready for maintainer review |
802+
760803
### New Specification Workflow
761804

762805
1. User creates issue with descriptive title (e.g., "3D scatter plot with rotation animation")

‎README.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -118,24 +118,23 @@ pyplots/
118118

119119
We welcome contributions! **All code is AI-generated** - you propose ideas, AI implements them.
120120

121-
**How to contribute**:
121+
**Three ways to contribute** (from [pyplots.ai](https://pyplots.ai) or GitHub):
122122

123-
1. **Propose plot ideas** - Create GitHub Issue with plot description (what you want to visualize)
124-
2. **Improve specs** - Suggest better descriptions for existing plots
125-
3. **Report issues** - Found bugs or quality problems? Open an Issue
126-
4. **Improve docs** - Help others understand the project
123+
| Action | When to Use | From pyplots.ai |
124+
|--------|-------------|-----------------|
125+
| **Suggest Spec** | Propose a new plot type | "suggest spec" link in catalog |
126+
| **Report Spec Issue** | Problem with a specification | "report issue" link on spec page |
127+
| **Report Impl Issue** | Problem with a library implementation | "report issue" link on impl page |
127128

128-
**The workflow**:
129+
**How it works**:
129130

130-
1. You create Issue with plot idea + add `spec-request` label
131-
2. AI generates spec, creates feature branch
132-
3. Maintainer reviews and adds `approved` label
133-
4. 9 library implementations generate in parallel (tracked via live status table)
134-
5. AI quality review per library (≥ 90 instant, < 90 repair loop, ≥ 50 final threshold)
135-
6. Auto-merge to feature branch, then to main
131+
1. You create Issue (or click link on pyplots.ai)
132+
2. AI validates and processes your input
133+
3. Maintainer reviews and approves
134+
4. AI generates/fixes the code
135+
5. Automated quality review ensures excellence
136136

137-
**Important**: Don't submit code directly! If a plot has quality issues, it means the spec needs improvement, not the
138-
code.
137+
**Important**: Don't submit code directly! If a plot has quality issues, it means the spec needs improvement, not the code.
139138

140139
See [contributing.md](docs/contributing.md) for details.
141140

@@ -167,6 +166,6 @@ MIT License - see [LICENSE](LICENSE) file for details.
167166

168167
**Built by [Markus Neusinger](https://linkedin.com/in/markus-neusinger/)**
169168

170-
[⭐ Star us on GitHub](https://github.com/MarkusNeusinger/pyplots) • [🐛 Report Bug](https://github.com/MarkusNeusinger/pyplots/issues) • [💡 Request Feature](https://github.com/MarkusNeusinger/pyplots/issues)
169+
[⭐ Star us on GitHub](https://github.com/MarkusNeusinger/pyplots) • [💡 Suggest Spec](https://github.com/MarkusNeusinger/pyplots/issues/new?template=spec-request.yml) • [🐛 Report Issue](https://github.com/MarkusNeusinger/pyplots/issues/new?template=report-issue.yml)
171170

172171
</div>

0 commit comments

Comments
 (0)