docs(issues): ask reporters what triage actually needs, without requiring it - #469
Merged
Conversation
…ring it Replaces the two stock templates with issue forms. The bug form adds the questions that repeatedly had to be asked by hand: how Markpad was installed, the Linux session and GPU, and the document that triggers the bug. It also says one problem per issue, since items appended to a report get lost in the thread. No field is required. A half-filled report is worth more than an abandoned one, so the structure does the work: a dropdown is less effort than typing, and a labelled empty section still tells a triager what is missing. Blank issues stay enabled — the maintainer-facing decision issues are written freehand and should not be pushed through a bug form. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Closed
PathGao
added a commit
that referenced
this pull request
Aug 22, 2026
…eeps reconstructing (#703) * docs(issues): cut the dead fields, and ask feature requests which platform they are for Measured against the 27 external issues filed since the templates were last rewritten (#469): - bug report, 10 fields -> 6. "Linux only: distribution, session and GPU/driver" was answered 0/9 times because it is skipped on Windows and macOS; it is now a line in the OS placeholder. "Anything else" 0/9, "The document, if one triggers it" 1/9 and "Screenshots" 3/9 collapse into one box. "What you expected" folds into "What happens". Version, install method and OS were answered 9/9 and are now required. - feature request, 3 fields -> 4. It carried no environment at all, so all 17 requests arrived without one — including Windows-only asks (tray icon, Scoop, a CLI flag) that cannot be triaged without knowing the platform. Adds a platform dropdown and a one-line version/install field, and drops "What have you tried instead?" (8/17) into the first placeholder. - question, 3 fields -> 2. Goal and what-you-tried merge. * docs(issues): ask for the raw Markdown as text, and for a reference app Two fields added back on evidence from the maintainer replies, where the information had to be reconstructed by hand: - "The Markdown that triggers it" leaves the combined box and becomes its own `render: markdown` field. #690 and #691 both pasted a screenshot of Markdown, and both answers had to read the trigger back out of the image before they could be tested. - "Has another app got this right?" is new on the feature request. The two requests that were answered fastest, #701 and #681, each attached a screenshot of another editor unprompted; #683, #604, #669 and #690 had to have Typora, Obsidian, Notion or GitHub named by the maintainer before the request had anything to be measured against. --------- Co-authored-by: PathGao <gaoyanbo@gaoyanbodeMacBook-Air.local>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces
bug_report.mdandfeature_request.mdwith three Issue Forms plus aconfig.yml.This changes what every future reporter sees, so it is your call as much as ours. The case below is built from issues already open, not from a view about how templates ought to look.
Nothing is required
No field in any of the three forms carries
validations: required. A required field is a place to abandon the form, and a half-filled report is worth far more than no report. The value comes from structure instead: a dropdown is less work than typing a sentence, and a labelled empty section still tells a triager exactly what is missing. Where a field looked tempting to require, the placeholder got better instead.What each new bug field is buying, and from which issues
How did you install Markpad? (dropdown) — the highest-value addition, and the current template never asks. Five open issues turn on the answer:
MarkpadInstaller_2.6.5_x64.exefails withos error 3; the portableMarkpad_2.6.5_x64.exeopens fine. The whole report is installer-vs-portable and only became legible because the reporter happened to try both.WebKitNetworkProcessunder the extracted image.This call is not available inside the sandbox), not app logic.In every one of those, "which artifact" is the bug.
Not sureis deliberately in the list — without it, people who genuinely don't know skip the field instead, and we lose the ones who could have picked correctly from a list.Linux only: distribution, session and GPU/driver (input) — "Linux" alone localises nothing. The two Linux issues above resolved on details the reporter volunteered without being asked: #182 needed Intel Arc + Mesa + Wayland/X11 to point at EGL, and #162 needed snap confinement. Marked Linux-only so Windows and macOS reporters skip it.
App version (input) — placeholder shows the shape (
2.7.0), because "latest" is useless the moment a release goes out and cannot be reconstructed afterwards.The document, if one triggers it (textarea) — #99 has been open since April and is still unreproduced: it is a PDF header-clipping report with a screenshot and no source
.md, and the last comment on it is a request for a reproduction. #201 shows the other side — that reporter offered the file unprompted ("I can provide the MD file privately"), so asking plainly is likely to work.One problem per issue (markdown note, not a checkbox) — #153 arrived as one bug plus two more in a
PSand aPPS. The titled bug was answered; the scroll-position item and the save-crash item sat unaddressed for over two months, and the crash has still never been reproduced. The note says to open them separately and explains why. It is guidance, not a box to tick — a checkbox here would just be a required field wearing a disguise.The other two forms
feature_request.yml— three fields: problem, proposal, what you tried instead. The stock template's four-heading ceremony is dropped.question.yml— Discussions are off (and turning them on needs admin), so questions arrive as issues, currently unlabelled. [QUESTION] Width of exported HTML #467 and Opening an untrusted .md can phone home: CSP img-src allows https:, and asset scope is the whole filesystem #394 are recent examples. This gets themquestionautomatically.config.yml
blank_issues_enabled: true, deliberately: the maintainer-facing decision issues here (#390, #394, #395, #396) are written freehand and must not be forced through a bug form. No contact links, since Discussions are off.Verification
ids within each file (10/3/3, no collisions), nomarkdownelement carrying anid, and novalidations.requiredanywhere.bug_report.ymlas a form preview on this branch with no validation banner — a malformed form would silently fall back to a blank issue instead.npm run check— 644 files, 0 errors, 0 warnings.npm test— 683 passing, 0 failing. No source file is touched; no workflow validates.github/.One wording note
The two Windows dropdown options are worded
installer (Markpad_…_setup.exe)andportable (Markpad_….exe)rather than pinned to_x64, since releases also shiparm64-setup.exeandarm64.exeand those users would otherwise land onNot sure. Same two options, same installer-vs-portable axis.