Python
docs: add contributor setup and validation guide
Ayush Tiwari2d440cd9fab4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 00000000..8d9fd9c7--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,70 @@+# Contributing to OpenWorker++Thanks for helping improve OpenWorker. Start with the [README](README.md) for the+product overview and local development setup. This guide covers the contribution+workflow.++## Pick a change++Search [open issues](https://github.com/andrewyng/openworker/issues) and+[open pull requests](https://github.com/andrewyng/openworker/pulls) before+starting. Check the issue discussion and the PR list for the issue number or+relevant code path so you do not duplicate active work. For a new feature or a+large behavior change, discuss the direction in an issue first: the project has+an active internal roadmap. For security vulnerabilities, follow+[SECURITY.md](SECURITY.md) and report privately.++Prefer a focused PR with a reproduction, the smallest useful fix, and a+regression test. Keep unrelated cleanup on a separate branch.++## Prepare your fork++Python 3.10 or newer and Node.js 20 are required by the project metadata and+CI. For desktop development, install the platform prerequisites for Tauri 2;+the browser UI and Python tests do not need a packaged desktop app.++Fork the repository on GitHub, then run:++```bash+git clone https://github.com/<your-user>/openworker.git+cd openworker+git remote add upstream https://github.com/andrewyng/openworker.git+git fetch upstream+git switch -c fix/short-description upstream/main+bash packaging/setup_dev_env.sh+```++On Windows, run the setup script from Git Bash or WSL. The README shows how to+start the server and browser UI; from `surfaces/gui/`, run `npm ci` before+GUI tests or development.++## Validate the change++Run the narrow checks while iterating, then the relevant full checks before+opening a PR:++| Changed area | Focused check | Full check |+| --- | --- | --- |+| Python backend | `.venv/bin/pytest tests/test_relevant_area.py -q` | `.venv/bin/pytest tests -q --cov=coworker --cov-report=term-missing` |+| GUI logic | `cd surfaces/gui && npm test -- --run path/to/relevant.test.tsx` | `cd surfaces/gui && npx tsc --noEmit && npm test` |+| GUI workflow | `cd surfaces/gui && npx playwright test e2e/relevant.spec.ts` | `cd surfaces/gui && npx playwright install chromium && npm run e2e` |++CI uses Python 3.12, Node 20, and the hermetic Playwright suite; it installs+`.[messaging,dev,bedrock]` for the Python job. Windows Python commands use+`.venv\\Scripts\\pytest.exe`. If you cannot run a check locally, say so in the+PR and include the checks you did run.++## Open a pull request++1. Rebase or merge the latest `upstream/main` into your branch and resolve any+ conflicts.+2. Commit the focused change and push your branch to your fork.+3. Open a PR targeting `andrewyng/openworker:main`. Link the issue and explain+ the failure, fix, and validation.+4. Attach before/after screenshots for visible UI bugs and changes, as requested+ in the README. For nonvisual changes, include a short reproduction and test+ output, and explain why a screenshot is not applicable.+5. Watch CI and review feedback; update the same branch with corrections.++A first-time fork's GitHub Actions run may require maintainer approval. Do not+interpret an unstarted workflow as a passing test.