From 64b6c523ef8dc0615bc5effcbecc173e3427ba6d Mon Sep 17 00:00:00 2001 From: Doxa Maps Date: Sun, 27 Sep 2026 23:28:40 +0000 Subject: [PATCH] A joining page for people who have never seen this repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dx-shepherd ENDTOKEN-UPG-DOC, from the Driver's laptop-first decision. Written for someone staring at a repo, a dev server and a database, unsure which one they are allowed to touch — so it answers that first and explains second. THE SHAPE, in the Driver's own three places: laptop = your workshop · main = the truth · the shared server = the table, look but do not edit. Plus the rule the whole thing rests on, one plugin folder per person. ★ THE 95% NUMBER IS THE POINT OF THE PUSH SECTION, not decoration. A newcomer whose first push is rejected assumes they broke something. The measured result — 95% of pushes rejected, 0 conflicts, 1.1 retries on average — tells them the rejection IS the normal case and explains why it is cheap: you collide on who goes first, never on the same lines, because you are never in the same file. That reframes a scary error into one extra command, and it is the strongest argument for the one-folder rule. ⚠ TWO THINGS I CORRECTED RATHER THAN SHIPPED: - I first cited `backend/pocketbase/pb_migrations` as the migrations path. It does NOT exist in this repo — it is from the architecture doc's PLAN. A path a reader cannot find is worse than no path, because they assume they cloned wrong. Now says "committed alongside the code" until it is real. - "reloads every few seconds" is now "about every 15 seconds", which is what the source actually states. NO INTERNAL NAMES, checked rather than intended: zero hits for the server hostnames, the source-control product, the agent tabs, the dictation tool, the auth stack, "tenant" or the project's own code names. Cross-linked to develop-a-plugin-and-see-it-live.md, which answers the different question of how to BUILD a plugin — this page is about working alongside other people once you have one. ⚠ THE ENV SECTION IS PROVISIONAL. DX_SYNC_REMOTE / DX_SYNC_BRANCH / DX_PB_URL are taken from the architecture doc; repo is building them now and I have asked for the exact names, which are required vs optional, and what each points at. A doc with a wrong env name is worse than no doc — the reader blames themselves — so this gets corrected the moment repo answers, before anyone links it. --- documentation/HOWTO-join-the-table.md | 144 ++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 documentation/HOWTO-join-the-table.md diff --git a/documentation/HOWTO-join-the-table.md b/documentation/HOWTO-join-the-table.md new file mode 100644 index 000000000..d72194dc3 --- /dev/null +++ b/documentation/HOWTO-join-the-table.md @@ -0,0 +1,144 @@ +# 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 hot-reload locally +too, put this in `.env.local`: + +``` +DX_SYNC_REMOTE= +DX_SYNC_BRANCH=main +``` + +Your laptop then fast-forwards onto `main` as people land. + +> **It never merges over your edits.** If your working copy is dirty, it leaves it alone. Uncommitted work +> cannot be overwritten by this — that is the whole reason it is a fast-forward and not a merge. + +This is optional. Skip it if you would rather pull manually. + +--- + +## 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 alongside the code. + +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. + +To point your laptop at the team's shared test data instead of your own: + +``` +DX_PB_URL= +``` + +Leave it unset and you get your local one, which is usually what you want while building. + +--- + +## 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.