diff --git a/documentation/HOWTO-join-the-table.md b/documentation/HOWTO-join-the-table.md new file mode 100644 index 000000000..275ab33b4 --- /dev/null +++ b/documentation/HOWTO-join-the-table.md @@ -0,0 +1,173 @@ +# How to join the table + +You want to build a map. Someone told you there is a repo, a dev server, and a thing called PocketBase, and +now you are staring at three of them wondering which one you are supposed to touch. + +Short answer: **you work on your laptop, you land your work on main, and a shared server shows everyone what +landed.** That is the whole shape. The rest of this page is what each of those three is for, and the five +commands you actually type. + +> **This page is about working alongside other people.** If you want to know how to build a plugin itself — +> the files, the build, getting it live — read +> [develop-a-plugin-and-see-it-live.md](./develop-a-plugin-and-see-it-live.md) first and come back here when +> you are ready to share your work. + +--- + +## The three places + +### 1. Your laptop — the workshop + +This is where you build. Everything is local and fast, and nothing you do here can affect anyone else. + +```bash +bun install +bun run dev +``` + +You get the Plugin Studio, hot reload on your own edits, and a local database with your own test data. Break +it, reset it, fill it with nonsense — it is yours. + +### 2. `main` — the truth + +When your work is ready, it goes to `main`. That is the one place everybody agrees on. Nothing is "real" +until it is there. + +### 3. The shared dev server — the table + +A server watches `main` and reloads about every 15 seconds. That is where the team sees each other's work without +anyone sending anyone a zip file. You do not edit here. You never need to log into it to do your job. + +> **The rule that makes this work:** one plugin folder per person. You edit `plugin-designs//` +> and nobody else does. Everything below depends on that. + +--- + +## Getting your work onto main + +Three commands, in this order, every time: + +```bash +git add -A && git commit -m "what you changed" +git pull --rebase origin main +git push origin HEAD:main +``` + +If the push is rejected, someone landed first. Run the middle command again and push again. That is not an +error — it is the normal case, and it is worth knowing how normal. + +**We measured it.** In a ten-writer stress test at a far faster edit rate than a human works at: + +| | | +|---|---| +| pushes rejected, then retried | **95%** | +| merge conflicts | **0** | +| retries needed per edit | 1.1 average, 3 at worst | + +Nearly every push got rejected. **Not one caused a conflict.** That is the one-folder-each rule paying off: +you are all pushing to the same branch, so you collide on *who goes first* — but never on the same lines of +code, because you are never in the same file. A rejected push costs you one extra command. It does not cost +you an afternoon untangling someone else's work. + +If you *do* hit a real conflict, it means two people edited one file. Stop and talk to the other person; +that is a coordination problem, not a git problem. + +--- + +## Seeing your teammates' work on your laptop (optional) + +By default your laptop only reloads on *your* edits. If you want teammates' landed work to arrive +automatically while `bun run dev` is running, copy `.env.example` to `.env.local` at the repo root and set: + +``` +DX_SYNC_REMOTE=origin +``` + +That is the only line you need. `.env.local` is never committed, so it stays yours. + +> **Either a remote name or a full repo URL works.** `origin` is what almost everyone wants. A URL — +> `https://…/your-repo.git` — works too and saves you a `git remote add`; if the repo is private it uses +> the git credentials your laptop already has. Leave it unset and the whole feature is off. +> +> If you do put a token in the URL (`https://user:token@…`), it is never written to the log or shown at +> `/api/dev-sync`. + +Two optional dials, if you want them: + +| | what it does | default | +|---|---|---| +| `DX_SYNC_BRANCH` | which branch to follow | `main` | +| `DX_SYNC_INTERVAL` | seconds between checks | `5` (minimum 2) | + +**It only pulls when it is completely safe to.** All three must be true: you are on that branch, you have no +unsaved edits, and you have no local commits. If any one of them is not, it does not touch your files — +it tells you instead, in the dev server log: + +``` +main is 3 commits ahead … pull when ready +``` + +So it cannot surprise you mid-thought. You can also check that any time at `/api/dev-sync`. + +--- + +## The database, and the one thing that surprises people + +There are three databases and you only ever touch one. + +| Where | What is in it | Who touches it | +|---|---|---| +| Your laptop | your own sandbox data | you, freely | +| The shared dev server | the team's shared test data | the team | +| Production | what the public sees | nobody directly | + +**You never publish a database.** Not yours, not anyone's. What travels is the *shape* — the tables and +fields — as migration files committed to the repo, in `backend/pocketbase/pb_migrations/`. + +So adding a field is a normal change: you edit, you commit the migration, you push it like any other file, +and it goes through review with everything else. When the person who publishes runs the publish step, the +migrations apply. + +This is deliberate. A database rule that opens something to the public arrives as **a commit someone can +read** rather than as a setting somebody clicked at midnight. If you have ever inherited a system where the +live config did not match the repo, you already know why. + +**You do not have to set up the database at all.** The first time you run `bun run dev` it downloads and +starts one for you, on your laptop, with its data in `.pb/`. You can open its admin screen from the dev +server at `/api/pb/_/`. + +The only time you touch this is if the log says port 8090 is already in use — then set `DX_PB_PORT` to +something else in `.env.local`. + +--- + +## One more thing to set + +The maps need a Mapbox token. It is the one credential you have to ask the team for: + +``` +VITE_MAPBOX_TOKEN= +``` + +That, plus `DX_SYNC_REMOTE=origin` if you want it, is the whole of `.env.local`. + +--- + +## The five things to remember + +1. **Build on your laptop.** It is fast and it is yours. +2. **One plugin folder per person.** This is what keeps ten people out of each other's way. +3. **`pull --rebase`, then push.** A rejected push is normal — 95% of them were, and none became conflicts. +4. **The shared server is for looking, not editing.** +5. **Schema is a commit, never a click.** You never publish a database. + +--- + +## When something is wrong + +- **"Your push was rejected"** — normal. `git pull --rebase origin main`, push again. +- **A real merge conflict** — two people edited one file. Talk to them; the one-folder rule slipped. +- **Your change is not on the shared server** — it reloads about every 15 seconds, not instantly. Check your + push actually landed: `git log origin/main -1`. +- **The shared server shows an old version of your plugin** — you are probably looking at what is on `main`, + not what is on your laptop. Those are different on purpose.