docs: add issue forms for player bug reports - #302
Merged
Conversation
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.
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
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.
Adds nine GitHub issue forms under
.github/ISSUE_TEMPLATE/, plus aconfig.ymlthat 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
01-quest.ymlQuest02-npc.ymlCreatures03-item.ymlLoot04-spell.ymlClass05-profession.ymlProffesion06-dungeon.ymlInstance07-object.ymlObject08-something-else.yml09-server.ymlCPPEvery form also applies
needs-triage.Design decisions worth flagging, since they are deliberate rather than accidental:
blank_issues_enabled: falseso nobody lands back on the empty box by accident.08-something-else.ymlis the escape hatch, and it says outright that picking the "wrong" template is not a problem.09-server.ymlis 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:
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
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:
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:
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-markdownfield has alabel, everydropdownhas a non-emptyoptionslist, andvalidationsis a sibling ofattributesrather than nested inside it. One nesting error in09-server.ymlwas 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
Proffesionwith its current spelling, which the forms match deliberately rather than correcting.How to Test the Changes:
[Quest]and the labelsQuest+needs-triageare applied, and that leaving every optional field blank still submits.render: textbox on the log field produces an unformatted code block.Known Issues and TODO List:
Proffesionlabel 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.