docs: issue templates, PR templates, and CONTRIBUTING.md

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,79 @@
+name: Bug report
+description: Report a defect so we can reproduce, fix, and verify it.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing the defect.
+      placeholder: "e.g. When I search for a route between rooms on different floors, the directions list comes back empty."
+    validations:
+      required: true
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current behavior
+      description: What actually happens? Include any error messages you see.
+      placeholder: "e.g. The page shows a blank directions panel and nothing is logged to the console."
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: What should happen instead?
+      placeholder: "e.g. The app should show turn-by-turn directions and a route line on the map."
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Numbered steps from a clean state. The goal is for a maintainer to reproduce the bug from your steps alone.
+      placeholder: |
+        1. Open the app (`just run`)
+        2. Set start room to "5.102" and end room to "2.201"
+        3. Click "Get directions"
+        4. Observe the empty directions panel
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, browser and version, how the app is run, and the branch/commit you're on.
+      placeholder: |
+        - OS: macOS 14.5
+        - Browser: Firefox 127
+        - How the app is run: `just run` / `just docker` / deployed
+        - Branch / commit: main @ abc1234
+      render: text
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Paste relevant console, terminal, or server logs. If you have none, write "N/A".
+      render: bash
+    validations:
+      required: false
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots or recordings
+      description: Drag and drop images or videos, or paste links to screen recordings that show the problem.
+      placeholder: "Attach screenshots or screen recordings here (drag & drop)."
+    validations:
+      required: false
+  - type: checkboxes
+    id: confirmation
+    attributes:
+      label: Confirmation
+      description: Before submitting, confirm you've checked for existing reports.
+      options:
+        - label: This issue is the first open report of this bug.
+          required: true

.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,48 @@
+name: Chore
+description: Refactor, documentation, data, infrastructure, or maintenance work with no product-facing change.
+title: "[Task]: "
+body:
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why is this work needed? What problem does it solve for the codebase or the team?
+      placeholder: "e.g. The routing module is hard to test because it holds too many responsibilities."
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-change
+    attributes:
+      label: Proposed change
+      description: What will change? Describe the approach at a high level.
+    validations:
+      required: true
+  - type: textarea
+    id: affected
+    attributes:
+      label: Affected modules or data
+      description: Which areas touch this? App code, tools, tests, data files, docs, or something else?
+      placeholder: "e.g. The module in app/logic/"
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: What outcome, when tested, shows this feature is complete?
+    validations:
+      required: false
+  - type: textarea
+    id: testing
+    attributes:
+      label: Testing requirements
+      description: What tests or validation are needed? (e.g. unit tests, `just validate-data` for data changes)
+    validations:
+      required: false
+  - type: textarea
+    id: risks
+    attributes:
+      label: Dependencies and risks
+      description: Other work this depends on, and anything that could go wrong or be hard to undo.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ideas & brainstorming
+    url: https://github.com/RC-MiniMap/MiniMap/discussions/categories/ideas
+    about: Open-ended ideas, proposals, and questions that aren't yet actionable issues.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,64 @@
+name: Feature request
+description: Propose a new feature or enhancement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or user need
+      description: What problem does this solve, and for who? Describe the need, not the solution.
+      placeholder: "e.g. Users on the ground floor have no quick way to find the nearest accessible restroom."
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-behavior
+    attributes:
+      label: Proposed behavior
+      description: How should the feature behave? What does the user see and do?
+      placeholder: "e.g. Add a 'Nearest restroom' button that highlights the closest restroom and shows a route to it."
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you considered and why you didn't choose them.
+      placeholder: "e.g. Filtering the room list by 'restroom' instead of a dedicated button — less discoverable."
+    validations:
+      required: false
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: What is in scope for this issue, and explicitly what is out of scope.
+      placeholder: |
+        In scope: the button and a route to the nearest restroom.
+        Out of scope: multi-building support, a native mobile app.
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: What outcome, when tested, shows this feature is complete?
+      placeholder: |
+        - Given a user on the ground floor, when they tap "Nearest restroom", a route to the nearest restroom is shown.
+        - The route reuses the existing pathfinding and directions.
+      render: markdown
+    validations:
+      required: false
+  - type: textarea
+    id: mockups
+    attributes:
+      label: Mockups or references
+      description: Links to mockups, sketches, or similar features elsewhere. Drag and drop images here.
+    validations:
+      required: false
+  - type: checkboxes
+    id: confirmation
+    attributes:
+      label: Confirmation
+      options:
+        - label: I searched existing issues and discussions and this hasn't already been proposed.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,58 @@
+## Summary
+
+<!-- One or two sentences: what does this PR do, at a high level? -->
+
+## Why
+
+<!-- Why is this change needed? What problem does it solve? -->
+
+## Related issue
+
+<!-- Link the issue this PR closes with a single closing keyword. -->
+Closes #NN
+
+<!-- Other options: Fixes #NN, Resolves #NN -->
+
+## What changed
+
+<!-- Bullet list of the meaningful changes. -->
+
+-
+
+## How it was tested
+
+<!-- How did you verify this? List the commands and scenarios you tried. -->
+
+-
+
+## `just check` result
+
+<!-- State the result of `just check`. If something fails, say why and what the follow-up is. -->
+- [ ] `just check` passes locally (matches CI)
+
+## Screenshots or recordings
+
+<!-- Required for UI changes. Drag and drop images/videos or paste links. Remove this section if not applicable. -->
+_N/A (no UI changes)_
+
+## Data or schema impact
+
+<!-- If this changes graph data or its schema, note it and confirm data validation passes. -->
+_N/A (no data/schema impact)_
+
+## Deployment or rollback considerations
+
+<!-- Only if applicable: migrations, environment variables, breaking changes, how to roll back. -->
+_N/A_
+
+---
+
+### Author checklist
+
+- [ ] Linked to one issue with a closing keyword (`Closes #…`, `Fixes #…`, or `Resolves #…`)
+- [ ] PR title uses Conventional Commit style (e.g. `feat:`, `fix:`, `docs:`) so the squashed commit is clear
+- [ ] Related tests updated and passing
+- [ ] `just check` passes and CI is green
+- [ ] Screenshots/recordings included for UI changes
+- [ ] `just validate-data` run for graph-data changes
+- [ ] I understand and can explain every change in this PR (including AI-written code)