Skip to content

docs: add issue forms for player bug reports - #302

Merged
svenbledt merged 1 commit into
HavenWoW:mainfrom
svenbledt:chore/issue-templates
Aug 15, 2026
Merged

docs: add issue forms for player bug reports#302
svenbledt merged 1 commit into
HavenWoW:mainfrom
svenbledt:chore/issue-templates

Conversation

@svenbledt

Copy link
Copy Markdown
Collaborator

Adds nine GitHub issue forms under .github/ISSUE_TEMPLATE/, plus a config.yml that turns off the blank issue box.

Why

Most people filing here are players, not contributors. They land on an empty text box and are asked, implicitly, to already know how a good bug report is structured — which quest ID matters, whether "it doesn't work" means the NPC is missing or the credit doesn't fire, what a maintainer needs in order to reproduce it. Reports come in thin, a maintainer asks three follow-up questions, and half the time the reporter is gone by then.

These forms ask those questions up front, in plain language, before the report is submitted.

What's in it

File Form Auto-label
01-quest.yml 🗺️ Quest problem Quest
02-npc.yml 👤 NPC or creature problem Creatures
03-item.yml 🎒 Item or loot problem Loot
04-spell.yml ✨ Spell, talent or class ability problem Class
05-profession.yml 🔨 Profession problem Proffesion
06-dungeon.yml 🏰 Dungeon or raid problem Instance
07-object.yml 📦 Object or vehicle problem Object
08-something-else.yml ❓ Something else
09-server.yml ⚙️ Server, build or crash CPP

Every form also applies needs-triage.

Design decisions worth flagging, since they are deliberate rather than accidental:

  • Written for someone who has never used GitHub. Each player-facing form opens with "You do not need to know anything about code or GitHub to fill this in. Answer what you can and leave the rest blank."
  • IDs are optional everywhere, with an inline "if you don't know it, leave this blank". Requiring a quest ID from a player is how you lose the report.
  • Every form asks both "what happened" and "what should have happened instead." The second half is the one that is almost always missing and almost always the useful one — it tells a maintainer what correct looks like.
  • Each form ends by asking reporters not to set a priority label, because a maintainer sorts that during triage. This is the counterpart to the label cleanup on the tracker: priority was being self-assigned by reporters, which meant it sorted nothing.
  • Screenshot fields explain drag-and-drop upload, because that is not obvious if you have not done it before.
  • blank_issues_enabled: false so nobody lands back on the empty box by accident. 08-something-else.yml is the escape hatch, and it says outright that picking the "wrong" template is not a problem.
  • 09-server.yml is the only contributor-facing form — build failures, crashes, performance — and it says so in its first paragraph so players self-select away from it.

Changes Proposed:

This PR proposes changes to:

  • Core (units, players, creatures, game systems).
  • Scripts (bosses, spell scripts, creature scripts).
  • Database (SAI, creatures, etc).

None of the above — this is repository tooling only. No C++, no SQL, no script or DB2 changes. Nothing in this PR is reachable from a running worldserver.

AI-assisted Pull Requests

  • AI tools (e.g. ChatGPT, Claude, or similar) were used entirely or partially in preparing this pull request.

Claude Opus 5, via Claude Code. The form copy and structure were drafted with it after a manual pass over the open tracker to work out which categories the real reports actually fall into and what information they were consistently missing.

Issues Addressed:

None directly. This is preventative — it is aimed at the quality of issues that have not been filed yet.

SOURCE:

  • Live research
  • Sniffs
  • Video evidence, knowledge databases or other public sources
  • Cherry-pick

Not applicable. This PR changes no game behaviour, so there is nothing to validate against retail or a sniff. The category split and the field list were derived from the currently open issues on this tracker.

Tests Performed:

  • Tested in-game by the author.
  • Tested in-game by other community members.
  • This pull request requires further testing and may have edge cases to be tested.

What was actually verified: all ten YAML files parse, and each was checked against GitHub's issue-form schema — every field has a valid type, every non-markdown field has a label, every dropdown has a non-empty options list, and validations is a sibling of attributes rather than nested inside it. One nesting error in 09-server.yml was caught this way and fixed before commit.

What was not verified, and cannot be from a branch: GitHub only serves issue templates from the default branch, so the template chooser and the rendered forms cannot be seen until this is merged. The labels each form applies must also already exist on the repo or GitHub silently drops them — they all exist today, including Proffesion with its current spelling, which the forms match deliberately rather than correcting.

How to Test the Changes:

  • This pull request requires further testing.
  1. Merge to the default branch.
  2. Open Issues → New issue. The chooser should list all nine forms and offer no blank-issue option.
  3. Open one player-facing form (🗺️ Quest problem is the busiest category) and submit a throwaway report. Confirm the title prefix [Quest] and the labels Quest + needs-triage are applied, and that leaving every optional field blank still submits.
  4. Open ⚙️ Server, build or crash and confirm the render: text box on the log field produces an unformatted code block.

Known Issues and TODO List:

  • The Proffesion label is misspelled on the repo. The forms match the existing spelling on purpose so labelling does not silently break. Renaming the label is a separate change, and would need these forms updated in the same commit.
  • Category boundaries will need adjusting once real traffic arrives — expect "Object or vehicle" and "Quest" to overlap, since a stuck vehicle is usually also a blocked quest.

Most reports on this tracker come from players rather than developers,
and several arrive with an empty body or with no indication of what the
correct behaviour would have been. Free-form issues assume knowledge of
git and of how a good bug report is structured, which is not a fair
assumption for the people actually finding these bugs.

Replaces free-form issues with nine forms, one per kind of report:
quest, NPC, item, spell, profession, dungeon, object/vehicle, a
catch-all, and one aimed at contributors building the core. Each asks
what happened and what should have happened instead, in plain language
with a worked example in every placeholder. IDs are optional throughout
and every field says so, since a player has no way to know them.

Each form applies its area label plus needs-triage, and every form ends
by asking the reporter not to set a priority. Contributors had been
marking almost everything Priority, which is what made the label
meaningless; the tier now belongs to whoever triages, not to whoever
reports. Blank issues are disabled because the catch-all form covers
anything that does not fit.

Verified: all ten files parse as YAML and pass a schema check for field
types, required labels and dropdown options, and all nine referenced
labels exist on the repository. Not verified: GitHub only renders issue
forms once they are on the default branch, so the on-site appearance
cannot be checked until this merges.
@svenbledt
svenbledt merged commit 472a89a into HavenWoW:main Aug 15, 2026
2 checks passed
@svenbledt
svenbledt deleted the chore/issue-templates branch August 15, 2026 18:23
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