From d2c44380a4e39be241f2b0436b7f8c649a8731e7 Mon Sep 17 00:00:00 2001 From: jubnl Date: Tue, 21 Apr 2026 13:44:08 +0200 Subject: [PATCH] doc: add missing pages in wiki --- wiki/Contributing.md | 82 +++++++++++++++++++ wiki/Development-environment.md | 138 ++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+) create mode 100644 wiki/Contributing.md create mode 100644 wiki/Development-environment.md diff --git a/wiki/Contributing.md b/wiki/Contributing.md new file mode 100644 index 00000000..9a884aee --- /dev/null +++ b/wiki/Contributing.md @@ -0,0 +1,82 @@ +# Contributing + +Thanks for your interest in contributing to TREK! Here are the guidelines for submitting pull requests. + +## Before You Start + +- **Ask in Discord first** — Before writing any code, pitch your idea in the `#github-pr` channel on our [Discord server](https://discord.gg/NhZBDSd4qW). We'll let you know if the PR is wanted and give direction. PRs without prior approval will be closed +- **Check existing issues** — Look for open issues or discussions before starting work +- **Target the `dev` branch** — All PRs must be opened against `dev`, not `main` +- **One thing per PR** — Keep PRs focused on a single change. Don't bundle unrelated fixes + +## Pull Request Guidelines + +### Code Quality + +- Write clean, readable code that matches the existing style +- No unnecessary abstractions or over-engineering +- Don't add features beyond what was discussed in the issue +- Don't add comments unless the logic isn't self-evident +- Don't add error handling for scenarios that can't happen + +### What We Look For + +- **Does it solve the stated problem?** — The PR should match the issue it addresses +- **Is it minimal?** — No extra refactoring, no "while I'm here" changes +- **Does it break anything?** — Breaking changes are not acceptable +- **Is the code clean?** — Consistent style, no debug logs, no dead code + +### Commit Messages + +Use conventional commits: +``` +fix(component): short description of what was fixed +feat(component): short description of new feature +``` + +### PR Description + +Include: +1. **Summary** — What does this PR do? (1-3 bullet points) +2. **Test plan** — How was this tested? +3. **Related issue** — Link the issue (e.g. `Fixes #123`) + +### What Will Get Your PR Closed + +- PRs that weren't discussed and approved in `#github-pr` on Discord first +- PRs that add unnecessary complexity (e.g. a redo button when undo already exists) +- PRs with breaking changes +- PRs that change code style or formatting across unrelated files +- PRs that add dependencies without justification + +## Development Setup + +```bash +git clone https://github.com/mauriceboe/TREK.git +cd TREK + +# Server +cd server +npm install +npm run dev + +# Client (separate terminal) +cd client +npm install +npm run dev +``` + +- Server runs on `http://localhost:3001` +- Client runs on `http://localhost:5173` (with proxy to server) + +## Tech Stack + +| Layer | Technology | +|---|---| +| Frontend | React 18, TypeScript, Zustand, Leaflet, Tailwind CSS, Vite | +| Backend | Express, TypeScript, better-sqlite3 | +| Real-time | WebSocket (ws) | +| Database | SQLite with WAL mode | +| Auth | JWT (HS256), bcrypt, TOTP MFA, OIDC | +| Maps | Leaflet + react-leaflet, OSRM, Nominatim, CartoDB tiles | +| i18n | 13 languages (EN, DE, ES, FR, NL, IT, PT-BR, CS, PL, HU, RU, ZH, AR) | diff --git a/wiki/Development-environment.md b/wiki/Development-environment.md new file mode 100644 index 00000000..6d813515 --- /dev/null +++ b/wiki/Development-environment.md @@ -0,0 +1,138 @@ +# Developer Setup Guide + +> Before anything else, please read the [Contributing Guidelines](https://github.com/mauriceboe/TREK/blob/main/CONTRIBUTING.md). + +## Prerequisites + +- Node.js 22+ +- npm +- Git +- A GitHub account + +--- + +## 1. Fork & Clone the Repository + +Go to the [TREK repository](https://github.com/mauriceboe/TREK) and click **Fork** to create your own copy. + +Then clone your fork locally: + +```bash +# Clone your fork, checking out the dev branch +git clone -b dev git@github.com:your-username/TREK.git +cd TREK +``` + +--- + +## 2. Configure Git Remotes + +Add the original repository as `upstream` so you can pull in future updates: + +```bash +git remote add upstream git@github.com:mauriceboe/TREK.git +``` + +You should now have two remotes: + +| Remote | URL | Purpose | +|------------|----------------------------------------------|--------------------------------| +| `origin` | `git@github.com:your-username/TREK.git` | Your fork — push changes here | +| `upstream` | `git@github.com:mauriceboe/TREK.git` | Main repo — pull updates from here | + +--- + +## 3. Keep Your Fork Up to Date + +Before starting any work, make sure your local `dev` branch is in sync with upstream: + +```bash +git fetch upstream +git rebase upstream/dev # or: git merge upstream/dev +``` + +--- + +## 4. Create a Feature Branch + +Working on a dedicated branch keeps your changes isolated and makes PRs easier to review: + +```bash +git checkout -b fix/my-changes origin/dev +``` + +Branch naming conventions: +- `feat/short-description` for new features +- `fix/short-description` for bug fixes +- `chore/short-description` for maintenance tasks + +--- + +## 5. Install Dependencies + +Install dependencies for both the client and server: + +```bash +# Client +cd client +npm i + +# Server +cd ../server +npm i +``` + +--- + +## 6. Available Scripts + +### Server (`/server`) + +| Command | Description | +|----------------------------|------------------------------------------| +| `npm start` | Start the server (production) | +| `npm run dev` | Start the server in watch mode (tsx) | +| `npm test` | Run all tests | +| `npm run test:unit` | Run unit tests only | +| `npm run test:integration` | Run integration tests | +| `npm run test:ws` | Run WebSocket tests | +| `npm run test:watch` | Run tests in watch mode | +| `npm run test:coverage` | Run tests with coverage report | + +### Client (`/client`) + +| Command | Description | +|--------------------------|------------------------------------------------------| +| `npm run dev` | Start the Vite dev server | +| `npm run build` | Build for production (runs icon generation first) | +| `npm run preview` | Preview the production build locally | +| `npm test` | Run all tests | +| `npm run test:unit` | Run unit tests only | +| `npm run test:integration` | Run integration tests | +| `npm run test:watch` | Run tests in watch mode | +| `npm run test:coverage` | Run tests with coverage report | + +--- + +## 7. Commit & Push Your Changes + +```bash +git add . +git commit -m "fix: describe your change" + +# Push to your fork's dev branch +git push origin fix/my-changes:dev + +# Or if working directly on dev +git push origin dev +``` + +Then open a Pull Request from your fork to `mauriceboe/TREK` targeting the `dev` branch. + +--- + +## Tips + +- Always branch off from an up-to-date `dev` — run `git fetch upstream && git rebase upstream/dev` before starting new work. +- Run tests before pushing: `npm run test` in both `client/` and `server/`. +- Follow the commit message conventions described in the [Contributing Guidelines](https://github.com/mauriceboe/TREK/blob/main/CONTRIBUTING.md). \ No newline at end of file