public_git/bambuddy
1
0
Fork 0
mirror of https://github.com/maziggy/bambuddy.git synced 2026-09-30 03:01:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore(triage): tighten bug-report template + add Area dropdown to cut invalid-issue load

Browse Source 
170 issues have been closed with the `invalid` label (61 of them in
  the last 30 days alone — ~1 in 5 of all closed issues), almost always
  because the reporter hadn't run the in-app Connection Diagnostic or
  checked the documented troubleshooting page. The Connection Diagnostic
  shipped weeks ago but the bug-report form let people skip it: the
  "I ran it" checkbox was `required: false` and the Support Package
  field was optional. Tighten both.

  Form changes (.github/ISSUE_TEMPLATE/bug_report.yml):

  - Connection Diagnostic checkbox: required: false → true
  - Support Package field: required: false → true ("drag the .zip
    or explain why you cannot attach one")
  - New required textarea "Troubleshooting steps already taken" —
    forces the reporter to type WHAT they tried and WHICH wiki pages
    they checked before submitting. Empty answers can't submit.
  - Pre-form intro spells out the search → wiki → diagnostic →
    support package sequence and cites the 1-in-5 stat
  - Final-checks list grew from one to three required confirmations
    (searched issues + checked troubleshooting wiki + ran Connection
    Diagnostic for any connection/printing/camera issue)

  Bug categorization (the gap that motivated this):

  - Old `Component` dropdown was Bambuddy / SpoolBuddy / Both — no
    area triage signal
  - Replaced with two required dropdowns:
    - Product: Bambuddy / SpoolBuddy
    - Area: 15 options covering the actual feature surface +
      Other / not sure
  - Auto-label workflow (.github/workflows/auto-label-area.yml)
    reads the Area dropdown from the rendered issue body on
    open/edit and applies the matching area:* label. Tolerant of
    CRLF and the _No response_ placeholder, won't re-add on edit
    re-fires, warns on unknown Area values

  Maintainer hand-off — labels must exist BEFORE the workflow runs,
  since github-script's addLabels throws on missing labels. Create the
  16 labels (15 area:* + 1 area:unsorted) once via the `gh label create`
  commands captured in CHANGELOG / commit context.

  OS dropdown left untouched (Docker stays — per Martin).

  Printer Model dropdown verified against backend/app/utils/printer_models.py
  PRINTER_MODEL_MAP: all 13 current models present (X1 Carbon, X1, X1E,
  X2D, P1S, P1P, P2S, A1, A1 Mini, H2D, H2D Pro, H2C, H2S).
This commit is contained in:
maziggy
2026-05-24 16:20:14 +02:00
parent 1e734fb7c6
commit e5ebab7ab8
3 changed files with 165 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.yml
+70 -19
View File
@@ -6,17 +6,47 @@ body:
- type: markdown
attributes:
value: |
Thanks for taking the time to report a bug! Please fill out the form below.
Thanks for taking the time to report a bug!
**Before you submit, please:**
1. Search [existing issues](https://github.com/maziggy/bambuddy/issues?q=is%3Aissue) — your problem may already be reported or resolved.
2. Skim the [Troubleshooting wiki](https://wiki.bambuddy.cool/reference/troubleshooting/) — roughly 1 in 5 closed bug reports turn out to be setup or configuration issues already documented there.
3. If your printer won't connect / won't print / camera won't load, run the in-app **Connection Diagnostic** (printer card or System → Diagnostics) FIRST. Most connection bugs are diagnosed in 30 seconds by the diagnostic and need no GitHub issue.
4. Generate a **Support Package** from System → Download Support Package — without it, most bugs cannot be investigated.
- type: dropdown
id: component
id: product
attributes:
label: Component
description: Which part of the project is affected?
label: Product
description: Which product is affected?
options:
- Bambuddy
- SpoolBuddy
- Both
validations:
required: true
- type: dropdown
id: area
attributes:
label: Area
description: Which part of the product is affected? Pick the closest match — picking "Other" makes triage slower.
options:
- Printer connection / setup
- Print start / dispatch
- Filament / AMS / Spoolman
- Slicer integration (Bambu Studio / OrcaSlicer)
- Virtual Printer (VP)
- Camera / live view / timelapse
- Archives / library / files
- Statistics
- Print Queue / scheduling
- Notifications
- Authentication / users / permissions
- Updates / firmware check
- UI / display / theme / i18n
- API / integrations (Home Assistant, MQTT export, Obico, ...)
- SpoolBuddy kiosk / display
- Other / not sure
validations:
required: true
@@ -50,6 +80,22 @@ body:
validations:
required: true
- type: textarea
id: troubleshooting_tried
attributes:
label: Troubleshooting steps already taken
description: |
What did you try BEFORE opening this issue? Which wiki pages did you check? Which in-app diagnostics did you run?
This is required because roughly 1 in 5 issues opened turn out to be already-documented setup problems. A meaningful answer here saves a round-trip and helps everyone.
placeholder: |
- Ran the in-app Connection Diagnostic — result: ...
- Checked wiki page: <paste URL or page name>
- Tried restarting / re-adding the printer
- Searched closed issues for: "<keywords>"
validations:
required: true
- type: dropdown
id: printer
attributes:
@@ -79,7 +125,7 @@ body:
attributes:
label: Bambuddy Version
description: Which version of Bambuddy are you running? (Check Settings page)
placeholder: e.g., 0.1.5
placeholder: e.g., 0.2.5
validations:
required: true
@@ -128,22 +174,25 @@ body:
attributes:
value: |
---
### 📦 Support Package
### 📦 Support Package — REQUIRED
For faster debugging, please create and attach a **Support Package** from **Settings → System Info → Download Support Package**.
This includes logs, system info, and configuration (with sensitive data redacted).
Create and attach a **Support Package** from **System → Download Support Package**.
It bundles logs, system info, and configuration (sensitive data redacted) — without it, most bugs cannot be reproduced or investigated.
For detailed instructions on enabling debug logging, see: [Debug Logging Guide](https://wiki.bambuddy.cool/features/system-info/?h=debug#enable-debug-logging)
Detailed instructions: [Debug Logging Guide](https://wiki.bambuddy.cool/features/system-info/?h=debug#enable-debug-logging)
- type: textarea
id: logs
attributes:
label: Relevant Logs / Support Package
label: Support Package (.zip) and / or relevant logs
description: |
Attach a support package (.zip) or paste relevant logs here. Enable DEBUG mode for verbose logging.
💡 Tip: You can drag and drop files directly into this text box.
Drag and drop your support package .zip here, or paste relevant logs. Enable DEBUG mode for verbose logging.
Reports without a Support Package or logs almost always go back-and-forth for a week before any progress is made. If you genuinely cannot generate one (e.g. Bambuddy itself won't start), write WHY here.
placeholder: |
Drag and drop your support package .zip file here, or paste logs...
Drag and drop your support package .zip file here, or paste logs / explain why you cannot attach one...
validations:
required: true
- type: textarea
id: screenshots
@@ -162,15 +211,17 @@ body:
- type: checkboxes
id: checklist
attributes:
label: Checklist
label: Final checks
options:
- label: I have searched existing issues to ensure this bug hasn't already been reported
- label: I searched existing (open AND closed) issues and this bug hasn't already been reported or resolved
required: true
- label: I am using the latest version of Bambuddy
- label: I checked the [Troubleshooting wiki](https://wiki.bambuddy.cool/reference/troubleshooting/) and the relevant feature page for my issue
required: true
- label: I am using the latest version of Bambuddy (or the latest daily build)
required: true
- label: My printer is set to LAN Only mode
required: true
- label: My printer has Developer Mode enabled
required: true
- label: For a connection or printing problem, I ran the in-app Connection Diagnostic (printer card or System page) and included the result above
required: false
- label: For any connection / printing / camera issue, I ran the in-app Connection Diagnostic and included the result above
required: true
.github/workflows/auto-label-area.yml
+94
View File
@@ -0,0 +1,94 @@
# Auto-apply area:* label from the "Area" dropdown in bug_report.yml.
#
# The bug-report issue form renders dropdown values into the issue body as a
# section like:
#
# ### Area
#
# Printer connection / setup
#
# This workflow parses that section after issue creation/edit and adds the
# matching area:* label. Frees the maintainer from typing the same label on
# every new bug.
#
# Labels referenced here must already exist in the repo — see the
# `gh label create` commands in CHANGELOG for [0.2.5b1].
name: Auto-label Issue Area
on:
issues:
types: [opened, edited]
permissions:
issues: write
jobs:
apply-area-label:
runs-on: ubuntu-latest
if: github.event.issue.pull_request == null
steps:
- name: Apply area:* label from Area dropdown
uses: actions/github-script@v7
with:
script: |
const body = context.payload.issue.body || '';
// Map of Area dropdown value (lowercased, trimmed) → area:* label.
// Keep in lockstep with .github/ISSUE_TEMPLATE/bug_report.yml.
const areaMap = {
'printer connection / setup': 'area:connection',
'print start / dispatch': 'area:print-dispatch',
'filament / ams / spoolman': 'area:filament',
'slicer integration (bambu studio / orcaslicer)': 'area:slicer',
'virtual printer (vp)': 'area:vp',
'camera / live view / timelapse': 'area:camera',
'archives / library / files': 'area:archives',
'statistics': 'area:stats',
'print queue / scheduling': 'area:queue',
'notifications': 'area:notifications',
'authentication / users / permissions': 'area:auth',
'updates / firmware check': 'area:updates',
'ui / display / theme / i18n': 'area:ui',
'api / integrations (home assistant, mqtt export, obico, ...)': 'area:integrations',
'spoolbuddy kiosk / display': 'area:spoolbuddy',
'other / not sure': 'area:unsorted',
};
// GitHub issue forms render dropdown answers under a level-3 heading
// matching the field label. Capture the first non-blank line of the
// section. Tolerant of trailing whitespace and CRLF endings.
const match = body.match(/###\s+Area\s*\r?\n\s*\r?\n\s*([^\r\n]+)/i);
if (!match) {
core.info('No "Area" section found in issue body — skipping.');
return;
}
const picked = match[1].trim().toLowerCase();
// Strip any markdown bold the form might add (rare) and tolerate
// a "_No response_" placeholder some renderers insert for required-
// but-empty fields (shouldn't happen, the field is required).
if (picked === '_no response_' || picked === '') {
core.info('Area field empty — skipping.');
return;
}
const label = areaMap[picked];
if (!label) {
core.warning(`Unrecognised Area value: "${picked}". Update areaMap in auto-label-area.yml.`);
return;
}
// Don't re-add if already present (issue edit path).
const existing = (context.payload.issue.labels || []).map(l => l.name);
if (existing.includes(label)) {
core.info(`Label "${label}" already present — nothing to do.`);
return;
}
await github.rest.issues.addLabels({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.issue.number,
labels: [label],
});
core.info(`Applied label "${label}" to issue #${context.payload.issue.number}.`);
CHANGELOG.md
+1
View File
@@ -14,6 +14,7 @@ All notable changes to Bambuddy will be documented in this file.
- **Connection Diagnostic — self-service triage for "printer won't connect / won't print"** — A triage review of recently-closed issues found roughly a third were user-side setup errors (printer not in LAN developer mode, blocked ports, Docker bridge networking, wrong access code, printer on a different subnet), each costing a multi-round-trip "enable debug logging → build a support bundle → upload it" exchange. A new diagnostic (`backend/app/services/printer_diagnostic.py`) runs those checks automatically: TCP reachability of MQTT 8883 / FTPS 990 / RTSPS 322, LAN developer mode, Docker network mode, printer/host subnet match, and MQTT credential class — each returning a pass / fail / warn / skip status with a localized plain-language fix. Exposed via `GET /printers/{id}/diagnostic` (saved printer) and `POST /printers/diagnostic` (pre-save Add-Printer flow), and surfaced as a one-click "Run diagnostic" from the printer card actions menu (plus a quick button on the card when a printer is offline), the Add-Printer dialog, and a new Connection Diagnostic section on the System page. The in-app bug reporter scans configured printers when the report form opens and always shows the result — a healthy confirmation when nothing's wrong, or the detected problem and its fix inline — so setup mistakes get self-resolved instead of becoming GitHub issues. The GitHub `config.yml` troubleshooting link was repointed from the wiki source repo to the rendered troubleshooting page. Backend service unit tests (15) and frontend modal tests (3) added; all diagnostic strings translated across the 8 locales. Backend ruff clean, frontend build clean, i18n parity green.
### Changed
- **Bug-report template: tightened fields + new Area dropdown to cut invalid-issue triage load** — 170 issues have been closed with the `invalid` label (61 of them in the last 30 days alone — roughly 1 in 5 of all closed issues), nearly always because the reporter hadn't run the in-app diagnostics or checked the documented troubleshooting page. The template now forces engagement with the tools that were already shipped. **Form changes** (`bug_report.yml`): (a) the "I ran the Connection Diagnostic" checkbox flipped from `required: false` to `required: true`, so the form blocks submission until the reporter has actually used the diagnostic (or knowingly lied — higher friction than reading the doc); (b) the Support Package textarea is now `required: true` instead of optional, with the field's prompt rewritten to "Drag the .zip here, or explain why you cannot attach one" so users without a working Bambuddy still have a path; (c) a new required "Troubleshooting steps already taken" textarea sits between Steps to Reproduce and the printer-model dropdown, asking which wiki pages were checked and which in-app diagnostics were run — empty answers can't submit, which produces either real evidence or an admission that nothing was tried (both of which are useful for triage); (d) the pre-form markdown intro now spells out the "search → wiki → diagnostic → support package" sequence with a citation of the 1-in-5 stat so reporters understand the *why* before they reach the fields; (e) the final-checks list grew from one to three required confirmations (searched issues + checked troubleshooting wiki + ran Connection Diagnostic for connection/printing/camera bugs), with the wiki-checked confirmation linking to the rendered troubleshooting page. **Bug categorization** (the gap that motivated the rewrite): the old single `Component` dropdown only carried `Bambuddy / SpoolBuddy / Both` — useless for area triage. Replaced with TWO required dropdowns: `Product` (Bambuddy / SpoolBuddy) and `Area` (15 options covering the actual feature surface — connection, dispatch, filament/AMS, slicer, VP, camera, archives, stats, queue, notifications, auth, updates, UI, integrations, SpoolBuddy kiosk, plus an Other escape hatch). **Auto-labeling** (`.github/workflows/auto-label-area.yml`): on every issue open/edit, an `actions/github-script@v7` step parses the Area dropdown out of the rendered issue body (matching the `### Area\n\nValue` block GitHub forms produce) and applies the matching `area:*` label. Tolerant of CRLF, the `_No response_` placeholder, and the issue-edit re-fire path (won't re-add an already-present label). Unrecognised Area values emit a `core.warning` so missed sync between the form and the workflow map shows up in Actions logs. Maintainer hand-off: 15 `area:*` labels need to be created once via `gh label create` (see commit message for the exact commands) — labels referenced by the workflow but missing in the repo cause the `addLabels` call to throw, so this prerequisite is load-bearing. Printer Model dropdown verified against `PRINTER_MODEL_MAP` in `backend/app/utils/printer_models.py` — all 13 current Bambu models present (X1 Carbon / X1 / X1E / X2D / P1S / P1P / P2S / A1 / A1 Mini / H2D / H2D Pro / H2C / H2S), no update needed. YAML syntax validated via Python `yaml.safe_load` for both the template and the workflow.
- **Settings → SpoolBuddy: CPU load tile added to the device card** — The SpoolBuddy daemon's heartbeat already reports `load_avg` (1/5/15 min) and `cpu_count` via `system_stats` (see `spoolbuddy/daemon/system_stats.py`), but the device card on the Bambuddy SpoolBuddy settings only rendered CPU temp / memory / disk / system uptime. Adds a fifth tile next to CPU temp showing the 1-minute load average alongside core count and a percent-of-cores readout — for a 4-core Pi: `1.20 / 4 (30%)`. Falls back to a bare load number when `cpu_count` isn't reported, and the tile is hidden entirely when the daemon doesn't emit `load_avg` (older builds). Useful for spotting the "I2C/SPI stuck after idle overnight" pattern early — sustained high load before the bus dies points at runaway daemon work rather than a kernel hang. Translated across all 9 locales (de/es/fr/it/ja/pt-BR/zh-CN/zh-TW). Frontend build clean, i18n parity green.
- **Virtual printer: setup diagnostic + one-click slicer-certificate export** — Two recurring virtual-printer support pains, addressed on the Virtual Printers settings page. **(1) Setup check** — a new stethoscope action on each VP card runs `GET /virtual-printers/{id}/diagnostic` and shows a pass/fail/warn/skip checklist: VP enabled, services running, bind interface still exists, access code set, target printer (proxy mode), and — decisively — a live TCP probe of the FTP/MQTT/discovery ports on the bind IP. The manager swallows per-service start errors (`run_with_logging`), so a service object can exist while nothing is actually listening; probing the bind IP from outside is the only reliable signal, and it catches the common "VP doesn't show up in the slicer" bind-IP-conflict and stale-interface cases. New `backend/app/services/virtual_printer/diagnostic.py` + `VPDiagnosticResult` schema + `VirtualPrinterDiagnosticModal.tsx`. **(2) Slicer certificate** — virtual printers present a TLS cert signed by a shared CA the slicer must trust; until now users had to `docker exec` in and `cat bbl_ca.crt` to get it. A new "Slicer certificate" row on the Virtual Printers settings card (alongside the Archive name source toggle) offers Copy and Download (`bambuddy-virtual-printer-ca.crt`) plus the CA's SHA-256 fingerprint, served by `GET /virtual-printers/ca-certificate` — only the public certificate, never the CA private key. The CA is generated on demand so the button works before the first VP is enabled. Copy uses a non-secure-context fallback (Bambuddy is usually on plain-HTTP LAN), extracted into a shared `utils/clipboard.ts`. 9 backend diagnostic/CA unit tests + 4 route integration tests + 6 frontend tests (diagnostic modal, clipboard helpers); all `vpDiagnostic.*` / `virtualPrinter.caCert.*` strings translated across the 9 locales. Backend ruff clean, frontend build clean, i18n parity green.
- **Bug-report panel: connection diagnostic no longer overflows on multi-printer setups** — The "Report a Bug" panel scans every configured printer on open and surfaces connection problems inline so users can self-fix before filing. The first cut rendered a full ~6-row checklist for *each* problem printer stacked vertically; a user with many printers all reporting issues pushed the description box, screenshot uploader and Submit button far below the fold in the `max-w-md` / `max-h-[80vh]` panel. The diagnostic section is now a compact summary — one line ("N of M printers have connection issues") followed by the affected printers as collapsed rows (healthy printers count toward M but render no detail). Each row expands on demand to that printer's full checklist via the shared `Collapsible` widget; when exactly one printer has problems the row is auto-expanded since that's the case where inline detail is wanted with no extra click. The panel now stays a fixed ~3 lines plus one row per affected printer regardless of fleet size, keeping the report form reachable. Healthy-fleet confirmation line is unchanged. New `bugReport.diagnosticSummary` key (with `{{problems}}`/`{{total}}`) replaces the static `diagnosticHeading`; `diagnosticIntro` reworded to be printer-count-neutral and point at the expand affordance — both translated across all 9 locales. 2 new tests in `BugReportBubble.test.tsx` (multiple problems stay collapsed and expand on click; a single problem auto-expands); 11 tests green; frontend build clean; i18n parity holds at 4903 keys × 9 locales.