Skip to content

Cut the dead issue-form fields, and ask for the three things triage keeps reconstructing - #703

Merged
PathGao merged 2 commits into
masterfrom
docs/simplify-issue-templates
Aug 22, 2026
Merged

Cut the dead issue-form fields, and ask for the three things triage keeps reconstructing#703
PathGao merged 2 commits into
masterfrom
docs/simplify-issue-templates

Conversation

@PathGao

@PathGao PathGao commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

The three issue forms were last rewritten in #469, which deliberately made every field optional. Twenty-seven external issues have come in since, and they show two different problems — the bug form asks for things nobody answers, and the feature form does not ask for the one thing triage needs.

What the filled-in issues show

Bug report, 9 issues, 10 fields:

answered field
9/9 Markpad version, install method, OS and version
9/9 What happens
7/9 What you expected
4/8 Steps to reproduce
3/9 Screenshots
1/9 The document, if one triggers it
0/9 Anything else
0/9 Linux only: distribution, session and GPU/driver

The environment block is not the expensive part — it is answered every time. The tail is: four fields at or under a third, one of them structurally impossible to answer because it is skipped on Windows and macOS, and Windows and macOS are where the reports come from.

Feature request, 17 issues, 3 fields: no environment field exists, so all 17 arrived without one. Several of them are Windows-only asks — #702 (tray icon), #672 (Scoop), #671 (a CLI flag) — and the form gives no way to tell that apart from a cross-platform request without reading the prose and guessing.

Question, 1 issue in sixteen days, and it was relabelled enhancement (#676, a duplicate of #682).

What changed

Bug report, 10 fields to 7. Linux only: distribution, session and GPU/driver becomes a clause in the OS placeholder, so Linux reporters still get asked and everyone else stops seeing an empty box. Screenshots and Anything else collapse into one box. The document, if one triggers it stays a separate field and becomes The Markdown that triggers it, with render: markdown so the paste arrives as text: #690 and #691 each attached a screenshot of the Markdown, and both replies had to read the trigger back out of the image before it could be tested. At 1/9 the field looked dead, but the cost of it being empty was the highest of any field on the form. What you expected folds into What happens, since at 7/9 it is nearly always answered in the same breath. Version, install method and OS become required: they were already 9/9, so this costs reporters nothing and stops the occasional blank one.

Feature request, 3 fields to 5. Adds a required platform dropdown (All / Windows / macOS / Linux / Not sure) and an optional one-line version-and-install field. It also adds Has another app got this right?, which takes screenshots: #701 and #681 each attached one of another editor unprompted and are the two requests that were answered against something concrete, while #683, #604, #669 and #690 had to have Typora, Obsidian, Notion or GitHub named in the reply before there was a reference at all. What have you tried instead? (8/17) folds into the first placeholder.

Question, 3 fields to 2. Goal and what-you-tried merge; the platform line is now required.

Trade-offs

A dropdown rather than the bug form's three-field environment block on the feature request. Triaging an enhancement needs one bit — is this Windows-only — not a reproducible environment; asking for three lines to get one bit is what makes a form feel heavy. The version input stays optional and free-text for the cases where it matters ("the 2.7.4 export dialog should…").

Required fields on identity but not on content. GitHub's required: true blocks submission, so it is only safe on fields with a 100% answer rate already. Everything describing the problem stays optional, which is what #469 established and the fill rates support.

question.yml kept rather than deleted. One use in sixteen days is a case for deleting it, but discussions are off on this repository and blank issues are enabled, so removing it just moves those reports to a form with no platform field at all.

Not changed

blank_issues_enabled: true stays. Three of the recent issues used the wrong form for their content (#702 and #559 filed as feature requests are bugs; #676 filed as a question is a request) — that is a routing problem, and narrowing the entry points is a separate change from simplifying the forms.

YAML parses for all four files; GitHub validates the schema on push to the default branch.

PathGao added 2 commits August 22, 2026 22:05
…tform 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.
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.
@PathGao PathGao changed the title Cut the dead issue-form fields, and ask feature requests which platform they are for Cut the dead issue-form fields, and ask for the three things triage keeps reconstructing Aug 22, 2026
@PathGao
PathGao merged commit fe90527 into master Aug 22, 2026
1 check passed
@PathGao
PathGao deleted the docs/simplify-issue-templates branch August 22, 2026 14:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant