diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 8a8ef0fc3..af01773b1 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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: + - Tried restarting / re-adding the printer + - Searched closed issues for: "" + 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 diff --git a/.github/workflows/auto-label-area.yml b/.github/workflows/auto-label-area.yml new file mode 100644 index 000000000..c514e0a30 --- /dev/null +++ b/.github/workflows/auto-label-area.yml @@ -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}.`); diff --git a/CHANGELOG.md b/CHANGELOG.md index 6eac8eb00..8c59bc56b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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.