From ac2d82d754a91e4c803ee348dfc6f02d9a01cb07 Mon Sep 17 00:00:00 2001 From: Lars van der Zande Date: Thu, 9 Jul 2026 16:01:39 -0500 Subject: [PATCH 1/2] Add CONTRIBUTING.md collaboration guidelines Golden rules: check open issues/PRs before filing, declare planned work via draft PR with a TOUCHES list before starting. Shared quality gate, scope declaration via plan docs, conflict etiquette, AI-agent rules. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d34bc81 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to Lunar Pup + +This is a fully collaborative project — humans and AI agents working in parallel. These +rules exist so nobody steps on anyone's toes. They apply to everyone, human or agent. + +## The two golden rules + +1. **Check open issues and PRs before filing anything.** + ```bash + gh pr list --repo Tsurgcom/lunarpup --state open + gh issue list --repo Tsurgcom/lunarpup --state open + ``` + If something overlapping exists, comment there instead of opening a duplicate. + +2. **Open a PR for what you plan to work on — before or as you start, not when you + finish.** A draft PR with a clear title, the files/areas you expect to touch, and a + sentence on the approach is enough. This is how everyone else finds out what's claimed. + Big ideas floating in chat (e.g. a renderer rewrite) don't exist until they have an + issue or draft PR — declare them. + +## Declaring scope + +- In your PR body, list the files/directories you expect to touch (a `TOUCHES:` line). + Overlap with another open PR? Talk to its author *before* both of you sink time in. +- Roadmap work is tracked in `plans/lunar-pup-vision/` — each concern doc has + `TOUCHES` and `BLOCKED_BY`. Link the concern your PR implements. New large work + deserves its own plan doc in the same format. +- Keep PRs to one landable unit. A PR that rewrites the renderer *and* adds a gamemode + can't be reviewed or sequenced against anyone else's work. + +## Quality gate + +Every PR must pass before review is requested: + +```bash +bun install && bunx tsc --noEmit && bun test +``` + +Add tests for what you build. If your change has runtime behavior, say in the PR body how +you verified it live (not just typecheck). + +## Overlapping files are normal — clobbering is not + +Two PRs touching the same file is fine when coordinated: agree on merge order in PR +comments, and the later one rebases. Never resolve a conflict by discarding the other +side's behavior — combine both, and say so in the PR. + +## AI-agent etiquette + +Agents follow every rule above, plus: identify yourself in the PR body (which +harness/fleet, which plan concern), include your acceptance gate command, and never +force-push over a branch you didn't create. From 0cb5baa833a07eff6be04a5227e533398c37fc4c Mon Sep 17 00:00:00 2001 From: Lars van der Zande Date: Thu, 9 Jul 2026 16:14:55 -0500 Subject: [PATCH 2/2] Require a Netlify preview deploy before a PR goes ready-for-review Documents the zero-setup anonymous draft deploy and the own-account flow, and notes the WebSocket-server caveat for multiplayer previews. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d34bc81..adf52be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,6 +39,32 @@ bun install && bunx tsc --noEmit && bun test Add tests for what you build. If your change has runtime behavior, say in the PR body how you verified it live (not just typecheck). +## Preview your PR before marking it ready + +Every PR must be testable in a browser without the reviewer building it locally. Before +you flip a draft to **ready for review**, deploy a preview of your branch to your own +Netlify and put the URL in the PR description. + +Zero-setup (anonymous draft deploy — no account needed): + +```bash +bun run build +npx netlify-cli deploy --dir=dist --allow-anonymous +``` + +Or with your own Netlify account (one-time `npx netlify-cli login` + `npx netlify-cli init`, +then per-PR): + +```bash +npx netlify-cli deploy --build +``` + +Both print a unique draft URL — that's your PR preview. Details in `NETLIFY.md`. + +Note: Netlify only hosts the static game. The Bun WebSocket server doesn't run there, so +multiplayer on a preview needs `?ws=` pointed at a reachable server (or state +that your PR is frontend-only). + ## Overlapping files are normal — clobbering is not Two PRs touching the same file is fine when coordinated: agree on merge order in PR