diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..54ad7d6 --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/chore.yml b/.github/ISSUE_TEMPLATE/chore.yml new file mode 100644 index 0000000..0c781bf --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..04c6f41 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..c3e6abe --- /dev/null +++ b/.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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ef718b2 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,58 @@ +## Summary + + + +## Why + + + +## Related issue + + +Closes #NN + + + +## What changed + + + +- + +## How it was tested + + + +- + +## `just check` result + + +- [ ] `just check` passes locally (matches CI) + +## Screenshots or recordings + + +_N/A (no UI changes)_ + +## Data or schema impact + + +_N/A (no data/schema impact)_ + +## Deployment or rollback considerations + + +_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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bda35c0..161858f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,349 +1,143 @@ -## Contributing Guide +# Contributing to MiniMap -This document explains how we will contribute together in this project. +Thanks for contributing. This guide is the source of truth for how we propose work, open pull requests, and verify changes before merging. If something is ambiguous or missing, ask and then update this guide. -### Overview +## How we work, in one line -- Everyone works on their own feature branch. -- We keep branches up to date with `main` often. -- We use pull requests (PRs) to merge code into `main`. -- We do **not** commit directly to `main`. +**Issue → focused branch → pull request → `just check` + CI → review → squash merge.** ---- - -## Team Workflow (Quick Version) - -1. Start from the latest `main` -2. Create a feature branch -3. Make small commits often -4. Merge `main` into your branch regularly -5. Open a Pull Request (PR) when your feature is ready -6. Get review, fix feedback, then merge PR into `main` - ---- - -## Branch Rules - -### 1) Never work directly on `main` - -`main` should always stay stable. - -### 2) One branch per feature - -Use one branch for one feature. - -Branch name examples: - -- `feature/pathfinding-same-room` -- `feature/map-polyline-animation` -- `fix/start-end-validation` -- `docs/contributing-workflow` -- `simon/map-animation` - -### 3) Keep branch scope small - -Focus on one feature, don't edit across the whole codebase, smaller branches are easier to review, test, and merge. - ---- - -## Session Git Routine - -Run this flow every time you start and finish work. - -### Start of session - -```bash -git checkout main -git pull origin main # pull new commits from remote repository - -# If starting new work -git checkout -b feature/short-description - -# If continuing existing work -git checkout your-existing-branch -git merge main # merge stable features from main into your branch -``` - -### During session - -- Commit often -- Keep commits focused on one idea -- Write clear commit messages - -```bash -git add . -git commit -m "Add validation when start and end room match" ``` - -### End of session - -```bash -git checkout main -git pull origin main # pulls latest changes from remote repo -git checkout your-branch-name # switch back to your branch -git merge main # merge updated main branch into your branch -git push -u origin your-branch-name # first push, updates your branch to remote repository on GitHub -# later pushes can just be: -git push +Idea still uncertain? + → discuss it in GitHub Discussions (Ideas category) + → turn it into an actionable issue (bug / feature / engineering task) + → create a focused branch off an up-to-date `main` + → open a draft or ready pull request linked to that issue + → run `just check` and wait for green CI + → get it reviewed + → squash-merge it ``` ---- - -## Why We Merge `main` Often - -Regularly running `git merge main` in your branch helps: - -- Catch conflicts early -- Keep your feature compatible with teammate changes -- Make final PR merge smoother - -Recommended: - -- Before writing new code -- Always before opening a PR -- Any time `main` receives updates - ---- - -## Commit Guidelines - -### Commit often +## Prerequisites -- Commit after tiny, working changes. +- [uv](https://docs.astral.sh/uv/) - Python package manager and version manager +- [just](https://github.com/casey/just) - command runner (defines the commands below) +- [Docker](https://www.docker.com/) - only needed for the `just docker` dev environment and the `docker-config` check step +- Node.js - used by the frontend tests (`just test-frontend`) +The GitHub Actions CI workflow runs the exact same commands, so what passes locally should pass in CI. -### Commit messages should describe intent +## Common commands -Good: +Run `just` with no arguments to list every recipe. -- `Add shortest-path fallback for disconnected nodes` -- `Fix map line not rendering on mobile width` -- `Update README setup steps for uv sync` +| Command | What it does | +| --- | --- | +| `just install` | Install dependencies (`uv sync`) - run once after cloning | +| `just run` | Start the app at | +| `just check` | **Full pre-push gate.** Lint, formatting, tests, compile, data validation, and Docker config | +| `just docker` | Build and run the Docker development environment | -Avoid: +`just check` runs, in order: `lint`, `format-check`, `test`, `test-frontend`, `compile`, `validate-data`, `docker-config`. CI runs the same seven steps on every pull request to `main`, so a green `just check` is a good proxy for a green build. -- `fix stuff` -- `changes` -- `update` +For faster iteration while developing, use the focused commands: `just lint`, `just format`, `just format-check`, `just test`, `just test-frontend`, `just validate-data`, `just coverage`. Run the full `just check` before pushing. -### Keep commits clean +## Where ideas start -- Do not mix unrelated changes in one commit -- Avoid committing generated files unless needed -- Never commit secrets (API keys, passwords, tokens) +- **Concrete bug, feature, or task?** Open an issue using the right template: + - **Bug report** - something is broken + - **Feature request** - new or changed product behavior + - **Engineering task** - refactors, documentation, data, infrastructure, maintenance +- Add an ownership label (`backend`, `frontend`, `data`, `documentation`, `integration`) so the right people notice it. ---- +## Making a change -## Pull Request (PR) Process - -### 1) Push your branch +### 1. Start from an up-to-date `main` +Never commit directly to `main`. `main` must always stay stable and green. ```bash -git push -u origin your-branch-name -# Pushes your branch to GitHub -``` - -### 2) Open a pull request into `main` - -PR title format (something descriptive) - -- `feature: add room-to-room shortest path` -- `fix: handle missing node in route lookup` -- `docs: add contribution workflow` - -### 3) PR Description - -Include details about what changed and why - -### 4) Review with someone - -Before approving the PR, confirm that: -- The code is working, tests pass -- You and the reviewer both understand the change -- There are no merge conflicts with `main` - - -### 5) Merge PR (no direct commits to `main`) - -Once approved and checks pass, merge through GitHub. - ---- - -## Handling Merge Conflicts - -Conflicts are normal and expected. - -When `git merge main` reports conflicts (after you've updated your local `main` from `origin/main`): - -1. Open conflicted files and choose the correct final code -2. Test locally -3. Mark as resolved and commit - -```bash -git add . -git commit -m "Resolve merge conflicts with main" -``` - ---- - - -## Protect `main` on GitHub - -Repository settings can enforce workflow automatically: - -- Require pull requests before merging -- Require at least 1 approval -- Block force pushes to `main` -- Require branch to be up to date before merge - -This is strongly recommended for team projects. - ---- - -## Quick Command Reference - -```bash -# update local main git checkout main -git pull origin main - -# create feature branch -git checkout -b feature/your-feature - -# commit often -git add . -git commit -m "Your clear message" - -# keep branch fresh -git merge main - -# push branch -git push -u origin feature/your-feature +git pull origin main # make sure main is current +git checkout -b feat/short-description ``` ---- +Use a descriptive, prefixed branch name: -## VS Code / GitHub Desktop Cheatsheet +- `feat/room-to-room-routing` +- `fix/missing-node-route` +- `docs/contribution-workflow` +- `refactor/pathfinding-module` +- `chore/update-dependencies` -An alternative to using git in the terminal is VS Code or GitHub Desktop. -This follows the same team rules and gives the same result. +### 2. Keep the change small and focused -### Golden Rules (Same as Terminal Workflow) +**One issue, one focused pull request.** If a change grows, split it into smaller PRs. They're easier to review, test, and merge. Keep commits small and focused on a single idea. Merge `main` into your branch often to catch conflicts early. -- Work on your own feature branch -- Do not commit directly to `main` -- Keep your branch updated with `main` often -- Open PRs from `feature/...` -> `main` only +### 3. Open a pull request ---- +Push your branch and open a PR into `main`. The pull request template will remind you to: -## VS Code Workflow +- link the issue with a closing keyword: `Closes #…`, `Fixes #…`, or `Resolves #…` +- explain what changed and why +- show how you tested it +- attach screenshots/recordings for UI changes +- note data/schema impact and run data validation for graph-data changes -### 1) Start of session (update your local `main`) +**Open a draft PR early** for feedback if you want input before the work is finished. -1. Open VS Code in project folder -2. Open **Source Control** (branch icon on left) -3. Make sure branch is `main` (bottom-left branch name) -4. Click `...` -> **Pull** +### 4. Verify before merging -This is equivalent to: +- Update tests whenever behavior changes, and add tests for new behavior. +- For changes to graph data (`data/`), run `just validate-data` (also part of `just check`). +- For UI changes, include screenshots or a screen recording. +- Run `just check` and make sure CI is green before requesting review. -```bash -git checkout main -git pull origin main -``` +### 5. Review and merge -### 2) Create a new feature branch +- Request a review; a maintainer must approve before merging. +- Address feedback in follow-up commits and re-run `just check`. +- When approved, **squash-merge**, which is the default. Squashing keeps `main` history clean and gives one clear commit per PR. -1. Click current branch name (bottom-left) -2. Choose **Create new branch** -3. Name it like `feature/short-description` +**Title your PR in Conventional Commit style** so the squashed commit reads well: -Equivalent: +| Type | Use for | Example | +| --- | --- | --- | +| `feat` | new feature | `feat: add room-to-room shortest path` | +| `fix` | bug fix | `fix: handle missing node in route lookup` | +| `docs` | documentation | `docs: add contribution workflow` | +| `refactor` | code change with no behavior change | `refactor: simplify pathfinding module` | +| `test` | tests only | `test: cover empty-route edge case` | +| `chore` | tooling, deps, maintenance | `chore: pin ruff version` | -```bash -git checkout -b feature/short-description -``` +### Handling merge conflicts -### 3) Continue existing branch and merge `main` into it - -1. Switch to your feature branch (click branch name) -2. Click `...` -> **Branch** -> **Merge Branch...** -3. Select `main` -4. If conflicts appear, use VS Code Merge Editor and choose final code carefully -5. Save files, then commit conflict resolution - -Equivalent: +Conflicts are normal. Update your branch with `main`, resolve the conflicting files, run `just check`, and commit the resolution. ```bash -git checkout your-branch git merge main -``` - -### 4) Commit changes - -1. In Source Control, stage changed files (`+`) -2. Write a clear commit message -3. Click **Commit** - -Equivalent: - -```bash +# resolve conflicts in your editor +just check git add . -git commit -m "Your clear message" -``` - -### 5) Push branch - -1. Click **Publish Branch** (first time) or **Push/Sync Changes** (later) - -Equivalent: - -```bash -git push -u origin your-branch-name -# later -git push +git commit -m "Resolve merge conflicts with main" ``` ---- - -## GitHub Desktop Workflow (Alternative) - -If VS Code Source Control feels confusing, GitHub Desktop is simpler for many people: - -1. Fetch origin -2. Switch to `main` and pull latest -3. Switch back to your feature branch -4. Use **Branch** -> **Update from main** -5. Commit + Push -6. Open PR to `main` - ---- - -## Important PR Rule - -- Correct PR direction: `feature/...` -> `main` -- Avoid opening PRs like `main` -> `feature/...` manually -- If GitHub shows **Update branch** on your feature PR, using that button is okay (it updates your feature branch safely) +## Definition of done ---- +Before a PR can merge, all of these must be true: -## Conflict Checklist (When Merge Fails) +- [ ] Linked to one issue with a closing keyword +- [ ] Scope is focused on that one issue +- [ ] Tests updated (and added) for behavior changes; all tests pass +- [ ] `just check` passes locally and CI is green +- [ ] Screenshots/recordings included for UI changes +- [ ] `just validate-data` run for graph-data changes +- [ ] Reviewed and approved by a maintainer +- [ ] Squash-merged with a clear Conventional Commit title -1. Resolve all conflict markers in files -2. Run project locally and test -3. Commit with message like: `Resolve merge conflicts with main` -4. Push branch -5. Re-check PR +## AI-assisted contributions ---- +AI-assisted code is welcome but treated exactly like any other contribution: **the author is responsible for it.** Before merging, make sure you understand every change, have tested it, and can explain it in review. An AI tool doesn't change the bar. Checks must still pass and reviewers must still be able to follow the code. If you can't explain a piece of generated code, rewrite it until you can. -## Terminal Command ↔ VS Code Action Map +## Keeping `main` protected -- `git pull origin main` -> Source Control `...` -> **Pull** -- `git checkout -b feature/x` -> Branch name -> **Create new branch** -- `git checkout my-branch` -> Branch name -> **Switch branch** -- `git merge main` -> `...` -> **Branch** -> **Merge Branch...** -> `main` -- `git commit -m "msg"` -> Stage files + Commit message + **Commit** -- `git push` -> **Push** / **Sync Changes** +Rely on the rules above. We have branch protection enabled on `main`: require pull requests (no direct pushes). Keep branches up to date and require status checks to pass before merging.