Skip to content

Issue Tracking

1. tasks.md stays primary

tasks.md at the repository root is the running narrative log — what's in progress, what's backlog, what shipped and why, with the detail a GitHub issue's fields don't hold (commit ranges, doc fixes found along the way, what was deliberately not built). It stays that way.

GitHub Issues are the linkable, assignable backing store underneath it. Every #NN tasks.md uses from this point forward, and every new one, is a real GitHub issue — not an informal number invented in the doc. If you write #NN in tasks.md, a commit message, or an ADR, an issue with that number exists.

Historical note (2026-07-29): tasks.md's #1–#45 predate any GitHub issue actually existing for this repo — they were an informal internal counter, not real issue numbers, and GitHub can't be made to retroactively assign 45 specific numbers to match them. The three that were still open (#34, #36, #37) were backfilled as real issues and now carry both: their tasks.md heading keeps the old internal number for continuity with existing history (commit messages, cross-references elsewhere in the doc), annotated with the real GitHub number it maps to — e.g. ### #36 — ... — GitHub #1. The GitHub number is the one that goes in commit messages (Closes #1, not Closes #36) so GitHub's own auto-close actually fires. Every tasks.md entry opened after this note uses only its real GitHub number — no more internal counter, no more dual-numbering.

2. Opening an issue

Use the Bug report or Feature or task template — blank issues are disabled. Every issue gets:

  • Exactly one area label, matching the Code/ module it belongs to (§3). If it's genuinely cross-cutting, use area:core.
  • A milestone, matching the Documentation/ROADMAP.md milestone it belongs to, once that's known. It's fine to leave this unset while an issue is still being triaged.
  • bug or enhancement from the type templates already set that; add documentation / question / good first issue / help wanted as they apply.

A tasks.md entry with sub-parts (the way #34 split into #34a–#34d) becomes one parent issue plus a task list inside it (- [ ] #35 sub-part title), or separate linked issues each noting Part of #NN — pick whichever the split is big enough to justify. Don't invent letter suffixes on GitHub; issue numbers are already unique.

3. Area labels

One per Code/ module, plus the Milestone 7 modules that don't have a Code/ directory yet (named in ROADMAP.md) so issues have somewhere to go the moment that milestone starts:

Label Scope
area:bulletin Code/Bulletin
area:character Code/Character
area:core Code/Core, cross-cutting work
area:economy Code/Economy
area:interaction Code/Interaction
area:inventory Code/Inventory
area:items Code/Items
area:ownership Code/Ownership
area:ui Code/Ui
area:world Code/World
area:legacy Legacy Lua source / migration reference (legacy/, Documentation/Legacy/)
area:docs Documentation site tooling and cross-cutting docs work not owned by one module
area:crime Milestone 7 — not yet built
area:jobs Milestone 7 — not yet built
area:needs Milestone 7 — not yet built
area:chat Milestone 7 — not yet built
area:commands Milestone 7 — not yet built

This list is the same module taxonomy 04_GIT_WORKFLOW.md §2 uses for commit scopes — an issue's area label and its eventual commits' (scope) should match.

4. Milestones

One GitHub Milestone per open ROADMAP.md milestone:

GitHub Milestone Roadmap section
v0.5.0 — First playable Milestone 6
Milestone 7 — Remaining gameplay Milestone 7
Milestone 8 — Content migration Milestone 8
Milestone 9 — Polish and hardening Milestone 9
v9.8.0 — Release-prep Milestone 10
v9.9.0 — Player presence & admin tools Milestone 11

Milestones 1–5 are done and have no open GitHub Milestone — tasks.md's "Done" section and git tags already record them. When a new ROADMAP.md milestone is added, add its GitHub Milestone at the same time.

5. Linking commits to issues

Reference the issue in the commit body, not just tasks.md:

  • Refs #NN — this commit is part of the work, more is coming.
  • Closes #NN / Fixes #NN — this is the commit that finishes it. On merge to main, GitHub closes the issue automatically.
feat(inventory): RequestUseItem -- the Interaction framework's first RPC entry point

...

Refs #34

When the final commit for an issue lands and tasks.md gets its "Done" entry, close the loop in both places in the same push — the issue via Closes #NN, tasks.md via moving the entry to "Done (recent)".

6. Templates

.github/ISSUE_TEMPLATE/ has two forms — Bug report and Feature or task — plus a config.yml that disables blank issues and points to Documentation/ instead of a contact link. Both forms require an area; the feature/task form's Definition of Done checklist mirrors 00_CONSTITUTION.md §5 and is meant to be filled in at close time, not at open time.