Merge pull request #32 from DDecoene/feature/31-contributing

Document contributor workflow for GitFlow release branches (#31)

Author: DDecoene

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!--
+  Base branch: target the active release branch (release/vX.Y.Z), NOT main.
+  See CONTRIBUTING.md. GitHub defaults the base to main — change it.
+-->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+Refs #<!-- issue number -->
+
+## Checklist (Definition of Done)
+
+- [ ] PR base is the active **`release/vX.Y.Z`** branch (not `main`)
+- [ ] `npm test` (Vitest) passes
+- [ ] `npx playwright test` passes — includes a Playwright e2e case for any user-facing command/feature
+- [ ] Docs updated as relevant: `README.md`, `CHANGELOG.md` (under the milestone heading), `CLAUDE.md`
+- [ ] Screenshots retaken if the UI changed
+- [ ] No `Co-Authored-By` / AI attribution in commits

CHANGELOG.md

@@ -10,6 +10,9 @@ Versions follow [Semantic Versioning](https://semver.org/) — minor bump per su
 ## [1.1.0] — 2026-06-27 — Live multiuser data propagation
 
 ### Added
+- `CONTRIBUTING.md` rewritten for the GitFlow model: fork → branch off the active
+  `release/vX.Y.Z` → PR against that release branch (not `main`), plus a Definition of
+  Done section. Added a PR template and a README "Contributing" pointer. (#31)
 - `JOIN WITH <alias> TO <file> FOR <cond> [FIELDS <list>]` — materialize a combined
   snapshot table from two open work areas, computed by SQLite's join planner.
   Deviations from dBASE III (FOR required, `alias.field` dot syntax, SQL-predicate

CONTRIBUTING.md

@@ -26,17 +26,74 @@ See [CLAUDE.md](CLAUDE.md) for the full architecture overview and W3Script comma
 ## Running tests
 
 ```bash
-npm test                # Vitest — must be green before any PR
-npx playwright test     # E2E — requires the dev server running on :5173/:3000
+npm test                # Vitest — unit + integration; must be green before any PR
+npx playwright test     # E2E — auto-starts the dev server via playwright.config.ts
 ```
 
-## Making changes
+## Branching workflow (important — read this)
+
+WebBase-III uses **GitFlow with milestone-versioned release branches**, so the one
+thing that trips people up is the PR base: **you target the active release branch,
+not `main`.**
+
+- `main` holds only released, tagged code — it's branch-protected and PRs against it
+  can't be merged by contributors.
+- All work for a version integrates on that version's **`release/vX.Y.Z`** branch
+  (one per GitHub milestone). A [milestone](https://github.com/DDecoene/WebBaseIII/milestones)
+  maps 1:1 to its release branch — find the open milestone (e.g. `v1.1.0`) and that's
+  your base branch (`release/v1.1.0`).
+
+### Step by step
+
+```bash
+# 1. Fork on GitHub, then clone your fork and add upstream
+git clone https://github.com/<you>/WebBaseIII.git
+cd WebBaseIII
+git remote add upstream https://github.com/DDecoene/WebBaseIII.git
+git fetch upstream
+
+# 2. Branch off the CURRENT release branch (NOT main)
+git checkout -b feature/my-change upstream/release/v1.1.0
+
+# 3. ...make changes + tests, commit...
+
+# 4. Push to your fork
+git push -u origin feature/my-change
+```
+
+Then open the PR on GitHub and **change the base branch from `main` to
+`release/vX.Y.Z`** (the base dropdown defaults to `main` — you must switch it).
+Reference the issue with `Refs #N` in the body. Because the PR merges into a
+non-default branch, `Closes #N` won't auto-close the issue; the maintainer closes it
+on merge.
+
+To keep your branch current (we periodically merge `main` into open release
+branches): `git fetch upstream && git merge upstream/release/v1.1.0`.
 
 1. Open an issue first for anything non-trivial, so we can discuss the approach.
-2. Fork, branch, and keep PRs focused — one feature or fix per PR.
+2. Keep PRs focused — one feature or fix per PR.
 3. Add or update tests for what you change. Bug fixes need a regression test.
-4. Run `npm test` and make sure it passes.
-5. Update docs that your change makes stale: `README.md` command tables, `CHANGELOG.md` (Added / Fixed / Changed), and `CLAUDE.md` if architecture changed.
+
+## Definition of Done
+
+Your PR is expected to meet the project's
+[Definition of Done](CLAUDE.md#definition-of-done). In short:
+
+- **`npm test` and `npx playwright test` both pass.**
+- **Every user-facing command/feature ships with a Playwright e2e case** in the same
+  PR — a REPL command needs a `tests/*.spec.ts` case that types it and asserts the
+  rendered result. Unit coverage alone is not "done."
+- **CI gates the merge** — the `unit` and `e2e` jobs must be green on your PR. CI runs
+  for fork PRs automatically; the suite needs no secrets.
+- **Docs reflect the change** — update `README.md` command tables / feature list,
+  `CHANGELOG.md` (Added / Fixed / Changed under the milestone heading), and `CLAUDE.md`
+  if architecture changed. Retake screenshots if the UI changed.
+
+## Commit conventions
+
+Use concise, conventional-commit-style messages matching the existing history
+(`feat(...)`, `fix(...)`, `test(...)`, `docs: ...`). **Do not add `Co-Authored-By`
+trailers or any AI/assistant attribution** — commits are authored solely by you.
 
 ## What to work on
 

README.md

@@ -414,6 +414,13 @@ and CSV `COPY TO`/`APPEND FROM`. CI runs both Vitest and Playwright on every PR.
 
 ---
 
+## Contributing
+
+Contributions are welcome! WebBase-III uses **GitFlow** — fork the repo and open your
+PR against the **active `release/vX.Y.Z` branch** (the open milestone), not `main`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full fork → release-branch workflow and
+the Definition of Done.
+
 ## Contributors
 
 Huge thanks to everyone who has helped extend WebBase-III: