hermes-explorigin
6abcf0483c
All checks were successful
CI / test-and-build (push) Successful in 43s
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# Contributing to Navigator
|
|
|
|
Thanks for contributing! This file covers how to build, test, and verify changes
|
|
to the Navigator web app before opening a PR or pushing.
|
|
|
|
## Project layout (quick map)
|
|
|
|
```
|
|
scripts/osm-data.mjs # Overpass API data fetch -> static/data/<area>.geojson
|
|
scripts/osm-dump.mjs # .osm.pbf dump ingestion -> POIs + routable road graph
|
|
src/lib/routing.ts # pure routing math (A*, POI avoidance, turn-by-turn)
|
|
src/lib/routing.worker.ts# Web Worker entry that runs route() off the UI thread
|
|
src/lib/prefs.ts # unit-system preference (localStorage)
|
|
src/lib/savedPoints.ts # browser-local Saved Points store + export/import (merge)
|
|
src/lib/components/ # MapView, DirectionsPanel, LocationDialog, …
|
|
src/routes/+page.svelte # top-level page (loads the manifest)
|
|
```
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
npm install
|
|
|
|
# Fetch & build all static data (Overpass + dump). Uses committed data if you
|
|
# only need the frontend; see below for data-only commands.
|
|
npm run build
|
|
|
|
# For frontend work without re-fetching over the network:
|
|
npm run build:static # rebuilds just the static site from existing static/data
|
|
npm run dev # Vite dev server
|
|
```
|
|
|
|
Data-only commands (they hit Overpass / download .pbf — be mindful of rate
|
|
limits):
|
|
|
|
```bash
|
|
npm run build:data # Overpass fetch -> static/data/*.geojson
|
|
npm run build:dump # .osm.pbf ingestion -> *-poi.geojson + *-graph.json
|
|
```
|
|
|
|
## Running the automated checks
|
|
|
|
Run all three before considering a change done:
|
|
|
|
```bash
|
|
npm run check # svelte-check (types + Svelte diagnostics) — 0 errors/warnings
|
|
npm test # 33k+ offline regression checks (data, routing, saved points)
|
|
npm run build:static # static site must build cleanly
|
|
```
|
|
|
|
These run offline (no Overpass/Nominatim) and are exactly what CI runs on every
|
|
push. **If any of these fail, fix before pushing.**
|
|
|
|
## Continuous Integration
|
|
|
|
- CI runs on every push/PR via Gitea Actions (`.gitea/workflows/ci.yml`).
|
|
- It runs `npm ci`, `npm run check`, `npm test`, `npm run build:static`, and
|
|
verifies `build/index.html` + `build/data` exist.
|
|
- Requires a registered runner with the `host` label (host-mode, no Docker).
|
|
|
|
## Manual QA checklist
|
|
|
|
The automated tests cover the data and routing logic. Because this sandbox's
|
|
browser tooling only reaches public URLs (and cloud browsers are intentionally not
|
|
used), the **visual/interaction layer needs a manual local pass**. Open the app
|
|
locally (`npm run dev`, or serve `build/` with any static server) and verify:
|
|
|
|
1. **Empty-map click** opens a context dialog with **"Save point…"** — it does
|
|
**not** auto-save or auto-start routing.
|
|
2. **Existing-point click** (a POI/zone/path) opens the dialog showing its info
|
|
and a **"Directions from here"** action.
|
|
3. **"Directions from here"** pins the origin, opens the Directions panel, and
|
|
lets you pick a destination.
|
|
4. **Second-point click** offers **"Directions to here"**, which sets it as the
|
|
destination.
|
|
5. The **Directions** top-bar button and the top **"Data sources"** bar are
|
|
**gone** (routes start only via the context dialog).
|
|
6. **Saved Points** toggle in the legend shows/hides the purple saved-point pins.
|
|
7. **Preferences** → **Export / Import** round-trips saved points; import
|
|
**merges** (dedupes by id) rather than replacing.
|
|
8. Route computation shows a **live progress bar** and the UI stays responsive
|
|
(Web Worker is off the main thread).
|
|
9. **Drive mode** shows **turn-by-turn** steps (Head north / Turn right /
|
|
Arrive at destination); Walk mode shows distance + time without turn steps.
|
|
|
|
### Reporting an issue
|
|
|
|
If a checklist item fails, note:
|
|
- The step number and what you did.
|
|
- Expected vs. actual behavior.
|
|
- Any console errors (browser dev tools → Console).
|
|
- Screenshot if helpful.
|
|
|
|
Then either file it or paste the details here for a fix.
|
|
|
|
## Commit conventions
|
|
|
|
Angular-style, e.g.:
|
|
|
|
```
|
|
feat(directions): run route in a Web Worker with live progress
|
|
fix(ui): open context dialog on map click instead of auto-saving
|
|
refactor(prefs): drop redundant unit override
|
|
docs: document the context-dialog interaction
|
|
```
|
|
|
|
Commit small, logical units (often one per task) and keep CI green on each. |